SAP HANA Developer Guide - Get a Free Blog
SAP HANA Developer Guide - Get a Free Blog
SAP HANA Developer Guide - Get a Free Blog
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
<strong>SAP</strong> <strong>HANA</strong> Appliance Software SPS 05<br />
Document Version: 1.0 - 2012-11-29<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
PUBLIC
Table of Contents<br />
1 Overview. ....................................................................8<br />
2 <strong>SAP</strong> <strong>HANA</strong>. ...................................................................9<br />
2.1 The <strong>SAP</strong> <strong>HANA</strong> In-Memory Database. ................................................ 9<br />
2.1.1 Columnar Data Storage. ...................................................9<br />
2.1.2 Parallel Processing. ......................................................10<br />
2.1.3 Simplifying Applications. ..................................................10<br />
2.2 <strong>SAP</strong> <strong>HANA</strong> Database Architecture. ..................................................11<br />
2.3 <strong>SAP</strong> <strong>HANA</strong> Extended Application Services. ............................................12<br />
2.4 Refactoring <strong>SAP</strong> <strong>HANA</strong> Based Applications. ........................................... 15<br />
3 <strong>SAP</strong> <strong>HANA</strong> as a Development Platform. ............................................16<br />
3.1 <strong>Developer</strong> Scenarios. ........................................................... 16<br />
3.1.1 Scenario: Developing Native <strong>SAP</strong> <strong>HANA</strong> Applications. ............................. 17<br />
3.1.2 Scenario: Using Database Client Interfaces. .................................... 18<br />
3.2 Development Objects. ...........................................................19<br />
3.3 Repository. ...................................................................21<br />
3.4 <strong>SAP</strong> <strong>HANA</strong> Studio. .............................................................23<br />
3.4.1 Modeler Perspective. .................................................... 23<br />
3.4.2 <strong>SAP</strong> <strong>HANA</strong> Development Perspective. ........................................25<br />
3.4.3 Debug Perspective. ..................................................... 30<br />
3.4.4 Administration Console Perspective. ......................................... 31<br />
3.5 <strong>Get</strong>ting Started. ...............................................................32<br />
3.5.1 Adding a System. .......................................................33<br />
4 Setting Up Your Application. ....................................................34<br />
4.1 Setting up Delivery Units. ........................................................ 35<br />
4.1.1 Maintaining the Delivery-Unit Vendor ID. .......................................35<br />
4.1.2 <strong>SAP</strong> <strong>HANA</strong> Delivery Unit Naming Conventions. ..................................36<br />
4.1.3 Creating a Delivery Unit. ..................................................36<br />
4.2 Using <strong>SAP</strong> <strong>HANA</strong> Projects. ....................................................... 37<br />
4.2.1 <strong>SAP</strong> <strong>HANA</strong> Repository: Workspaces. .........................................38<br />
4.2.2 Creating a Repository Workspace. ...........................................39<br />
4.2.3 <strong>SAP</strong> <strong>HANA</strong> Studio Projects. ................................................39<br />
4.2.4 Creating a Project for <strong>SAP</strong> <strong>HANA</strong> XS. .........................................40<br />
4.2.5 Sharing a Project for <strong>SAP</strong> <strong>HANA</strong> XS. ......................................... 40<br />
4.2.6 Importing a Project in <strong>SAP</strong> <strong>HANA</strong> XS. .........................................41<br />
4.3 Maintaining Repository Packages. ..................................................42<br />
2<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Table of Contents
4.3.1 <strong>SAP</strong> <strong>HANA</strong> Repository Packages and Namespaces. ...............................43<br />
4.3.2 Defining Repository Package Privileges. .......................................46<br />
4.3.3 Creating a Package. .....................................................46<br />
4.3.4 Defining a Package Hierarchy. ..............................................47<br />
4.4 Creating the Application Descriptors. ................................................49<br />
4.4.1 The <strong>SAP</strong> <strong>HANA</strong> XS Application Descriptor. .....................................49<br />
4.4.2 Create an Application Descriptor File. .........................................50<br />
4.4.3 The Application-Access File. ...............................................50<br />
4.4.4 Application-Access File Keyword Options. ..................................... 53<br />
4.4.5 Application-Access URL Rewrite Rules. ....................................... 56<br />
4.4.6 Enabling Access to <strong>SAP</strong> <strong>HANA</strong> XS Application Packages. ...........................57<br />
4.4.7 The Application-Privileges File. ............................................. 59<br />
4.4.8 Create an <strong>SAP</strong> <strong>HANA</strong> XS Application Privileges File. .............................. 60<br />
4.5 Tutorial: My First <strong>SAP</strong> <strong>HANA</strong> Application. .............................................62<br />
4.5.1 Open the Development Perspective. ......................................... 62<br />
4.5.2 Add a System. .........................................................63<br />
4.5.3 Add a Workspace. ...................................................... 66<br />
4.5.4 Add a Project. ......................................................... 67<br />
4.5.5 Share Your Project. ..................................................... 68<br />
4.5.6 Write Server-Side JavaScript. ..............................................70<br />
4.5.7 Retrieve Data. ......................................................... 72<br />
5 Setting Up the Persistence Model. ................................................74<br />
5.1 Schema. .................................................................... 75<br />
5.2 Creating Schemas. .............................................................76<br />
5.3 Tables. ..................................................................... 76<br />
5.4 Creating Tables. ...............................................................77<br />
5.5 Sequences. ..................................................................78<br />
5.6 Creating Sequences. ............................................................79<br />
5.7 SQL Views. .................................................................. 80<br />
5.8 Creating SQL Views. ............................................................81<br />
5.9 Data Provisioning Using Table Import. ...............................................82<br />
5.9.1 Table-Import Model. .....................................................83<br />
5.9.2 Table-Import Data. ......................................................83<br />
5.9.3 Table-Import Extensions. ................................................. 84<br />
5.9.4 Table-Import Configuration-File Syntax. .......................................84<br />
5.10 Importing Data Using Table Import. .................................................85<br />
5.11 Using Imported Table Data in <strong>SAP</strong> <strong>HANA</strong>. .............................................87<br />
5.12 Using Imported Table Data in an <strong>SAP</strong> <strong>HANA</strong> XS Application. ................................88<br />
5.13 Extending a Table Import. ........................................................89<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Table of Contents<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 3
6 Setting Up the Analytic Model. ...................................................92<br />
6.1 Setting Up the Modeling Environment. ...............................................94<br />
6.1.1 Setting Modeler Preferences. .............................................. 94<br />
6.1.2 Configuring the Import Server. ............................................. 95<br />
6.1.3 Importing Table Definitions. ............................................... 95<br />
6.1.4 Loading Data into Tables. ................................................. 97<br />
6.1.5 Copying Content Delivered by <strong>SAP</strong>. ..........................................99<br />
6.1.6 Mapping the Authoring Schema to the Physical Schema. ..........................100<br />
6.1.7 Generating Time Data. ...................................................102<br />
6.2 Creating Views. ...............................................................103<br />
6.2.1 Attributes and Measures. ................................................ 103<br />
6.2.2 Attribute Views. .......................................................104<br />
6.2.3 Creating Attribute Views. .................................................105<br />
6.2.4 Analytic Views. ........................................................109<br />
6.2.5 Creating Analytic Views. ..................................................110<br />
6.2.6 Calculation Views. ......................................................115<br />
6.2.7 Creating Calculation Views . ...............................................116<br />
6.2.8 Assigning Variables. .................................................... 123<br />
6.2.9 Creating Input Parameters. ...............................................125<br />
6.2.10 Creating Hierarchies. ....................................................127<br />
6.2.11 Using Currency and Unit of Measure. ........................................130<br />
6.2.12 Activating Objects. .....................................................132<br />
6.3 Creating Decision Tables. ....................................................... 133<br />
6.3.1 Changing the Layout of a Decision Table. ..................................... 139<br />
6.3.2 Using Parameters in a Decision Table. ........................................139<br />
6.4 Managing Object Versions. ...................................................... 140<br />
6.4.1 Switching Ownership of Inactive Objects. .....................................140<br />
6.4.2 Toggling Versions of Content Objects. ........................................141<br />
6.4.3 Viewing Version History of Content Objects. ...................................142<br />
6.5 Working with Objects. ..........................................................142<br />
4<br />
6.5.1 Managing Layout. ......................................................142<br />
6.5.2 Filtering Packages and Objects. ............................................142<br />
6.5.3 Refactoring Objects. ....................................................143<br />
6.5.4 Validating Models . .....................................................144<br />
6.5.5 Generating Object Documentation. ..........................................144<br />
6.5.6 Enabling Multilanguage Support for Objects. ...................................145<br />
6.5.7 Checking Model References. .............................................. 145<br />
6.5.8 Viewing the Job Log. ....................................................146<br />
6.5.9 Maintaining Search Attributes. .............................................146<br />
6.5.10 Previewing Data of Content Objects. .........................................146<br />
6.5.11 Functions used in Expressions. .............................................147<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Table of Contents
6.5.12 Searching Tables, Models and Column Views. ..................................152<br />
6.5.13 Setting Keyboard Shortcuts. .............................................. 153<br />
6.5.14 Copying an Object. .....................................................154<br />
6.6 Importing BW Objects. ......................................................... 154<br />
7 Developing Procedures. ....................................................... 158<br />
7.1 Editing SQLScript. .............................................................159<br />
7.2 Debugging SQLScript. ..........................................................161<br />
7.3 Developing Procedures in the Modeler Editor. .........................................162<br />
8 Defining Web-based Data Access. ............................................... 164<br />
8.1 Data Access with OData in <strong>SAP</strong> <strong>HANA</strong> XS. ............................................164<br />
8.1.1 OData in <strong>SAP</strong> <strong>HANA</strong> XS. ................................................. 164<br />
8.1.2 OData Service Definitions. ................................................165<br />
8.1.3 OData URI Parameters, Query Options, and Features. ............................ 167<br />
8.1.4 OData Security Considerations. ............................................183<br />
8.1.5 Defining the Data an OData Service Exposes. ...................................183<br />
8.1.6 Creating an OData Service Definition. ........................................183<br />
8.1.7 OData Service Definition Language Syntax. ....................................184<br />
8.1.8 OData Service Definition: SQL-EDM Type Mapping. ..............................186<br />
8.1.9 OData Service-Definition Examples. .........................................188<br />
8.2 Data Access with XMLA in <strong>SAP</strong> <strong>HANA</strong> XS. ............................................201<br />
8.2.1 XML for Analysis (XMLA). ................................................201<br />
8.2.2 XMLA Service Definition. .................................................202<br />
8.2.3 XMLA Security Considerations. ............................................203<br />
8.2.4 Multidimensional Expressions (MDX). ....................................... 203<br />
8.2.5 MDX Functions. .......................................................204<br />
8.2.6 MDX Extensions. ...................................................... 207<br />
8.2.7 Defining the Data an XMLA Service Exposes. ...................................210<br />
8.2.8 Creating an XMLA Service Definition. ........................................210<br />
9 Writing Server-Side JavaScript Applications. .......................................212<br />
9.1 Data Access with JavaScript in <strong>SAP</strong> <strong>HANA</strong> XS. .........................................212<br />
9.2 Writing JavaScript Code. ........................................................212<br />
9.2.1 Server-Side JavaScript in <strong>SAP</strong> <strong>HANA</strong> XS. ..................................... 212<br />
9.2.2 JavaScript Editor. ......................................................213<br />
9.2.3 Server-Side JavaScript Security Considerations. ................................214<br />
9.2.4 Writing Server-Side JavaScript Applications. ...................................218<br />
9.3 Writing JavaScript Libraries. ..................................................... 219<br />
9.3.1 Server-Side JavaScript Libraries. ...........................................219<br />
9.3.2 Writing Server-Side JavaScript Libraries. .....................................220<br />
9.3.3 Importing Server-Side JavaScript Libraries. ...................................220<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Table of Contents<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 5
9.4 Server-Side JavaScript APIs. .....................................................221<br />
9.5 The SQL Connection Configuration File. .............................................222<br />
9.6 Tracing JavaScript. ............................................................224<br />
9.6.1 Server-Side JavaScript Tracing. ............................................224<br />
9.6.2 Tracing Server-Side JavaScript Applications. .................................. 224<br />
9.6.3 Viewing Server-Side JavaScript Application Trace Files. ...........................225<br />
9.7 Debugging JavaScript. ......................................................... 225<br />
9.7.1 Opening a Port for JavaScript Debugging. .....................................227<br />
10 Building UIs with <strong>SAP</strong>UI5. ..................................................... 229<br />
10.1 Installing <strong>SAP</strong>UI5 Application Development Tools. ......................................230<br />
10.2 Creating an <strong>SAP</strong>UI5 Application. ..................................................230<br />
10.2.1 Local Testing of a <strong>SAP</strong>UI5 Application. .......................................232<br />
10.2.2 <strong>SAP</strong>UI5 Runtime Version Comparison. .......................................233<br />
10.3 Supporting Translation. ........................................................ 234<br />
11 Enabling Search. ............................................................ 235<br />
11.1 Creating Full Text Indexes. ...................................................... 235<br />
11.1.1 Full Text Index Types. ...................................................237<br />
11.1.2 Synchronization. ...................................................... 240<br />
11.1.3 Text Analysis. .........................................................242<br />
11.1.4 Dropping Full Text Indexes. ...............................................246<br />
11.1.5 Altering Full Text Index Parameters. .........................................246<br />
11.1.6 Full Text Index Parameters. ...............................................247<br />
11.2 Building SQL Search Queries. .................................................... 252<br />
11.2.1 Search Queries with CONTAINS. ...........................................252<br />
11.2.2 EXACT Search. ........................................................255<br />
11.2.3 LINGUISTIC Search. ....................................................256<br />
11.2.4 FUZZY Search. ........................................................256<br />
11.3 Building Search Apps. ..........................................................308<br />
11.3.1 Introduction to the UI Toolkit for Info Access. ..................................308<br />
11.3.2 Installing the Service and the Toolkit. ........................................309<br />
11.3.3 <strong>Get</strong>ting to Know the Demo App. ............................................310<br />
11.3.4 <strong>Get</strong>ting to Know the Demo HTML. ...........................................311<br />
11.3.5 Preparing Your Source Data. ..............................................312<br />
11.3.6 Connecting Your Source Data. .............................................314<br />
11.3.7 Defining the Page Layout. ................................................ 315<br />
11.3.8 Configuring the Widgets. .................................................315<br />
11.3.9 Defining the Layout of Result Lists and Details. ................................. 319<br />
12 Setting Up Roles and Authorizations. .............................................320<br />
12.1 The Authorization Model. ....................................................... 320<br />
6<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Table of Contents
12.2 Authentication Overview. ........................................................321<br />
12.3 Roles. ..................................................................... 321<br />
12.3.1 Roles. ..............................................................322<br />
12.3.2 Roles as Repository Objects. ..............................................323<br />
12.3.3 Creating Roles in the Repository. ...........................................324<br />
12.4 Privileges. ..................................................................329<br />
12.4.1 System Privileges. ..................................................... 329<br />
12.4.2 Object Privileges. ......................................................329<br />
12.4.3 Package Privileges. .....................................................330<br />
12.4.4 Analytic Privileges. .....................................................332<br />
12.4.5 Creating Analytic Privileges. ...............................................341<br />
12.4.6 Granting Privileges to Users. ..............................................345<br />
12.5 Application Access. ........................................................... 346<br />
13 Implementing Lifecycle Management . ............................................348<br />
13.1 <strong>SAP</strong> <strong>HANA</strong> Delivery Units. .......................................................348<br />
13.2 The <strong>SAP</strong> <strong>HANA</strong> Delivery-Unit Lifecycle. ............................................. 348<br />
13.3 Exporting Delivery Units. ........................................................349<br />
13.4 Importing Delivery Units. ........................................................351<br />
13.5 Translating Delivery Units. .......................................................352<br />
13.5.1 <strong>SAP</strong> <strong>HANA</strong> Delivery-Unit Translation Details. ...................................353<br />
13.5.2 Maintaining Translation Details. ............................................353<br />
14 Using Database Client Interfaces. ............................................... 355<br />
14.1 Connecting via ODBC. ..........................................................355<br />
14.1.1 Using the User Store. ...................................................356<br />
14.1.2 Testing the ODBC Installation. .............................................357<br />
14.2 Connecting via JDBC. ..........................................................358<br />
14.2.1 Tracing JDBC Connections. ...............................................359<br />
14.2.2 Valid Java-to-SQL Conversions. ............................................361<br />
14.3 Connecting via ODBO. ..........................................................362<br />
14.3.1 Connecting with Microsoft Excel. ...........................................362<br />
14.3.2 Multidimensional Expressions (MDX). ....................................... 365<br />
14.3.3 MDX Functions. .......................................................366<br />
14.3.4 MDX Extensions. ...................................................... 370<br />
15 <strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> References. ...............................................373<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Table of Contents<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 7
1 Overview<br />
This guide presents a developer’s view of <strong>SAP</strong> <strong>HANA</strong> ® . It explains how to use the <strong>SAP</strong> <strong>HANA</strong> development tools to<br />
create comprehensive analytical models and to build applications with <strong>SAP</strong> <strong>HANA</strong>'s programmatic interfaces and<br />
integrated development environment, including to develop native code that runs inside <strong>SAP</strong> <strong>HANA</strong>.<br />
The guide is organized as follows:<br />
● <strong>SAP</strong> <strong>HANA</strong> [page 9] describes the capabilities of <strong>SAP</strong> <strong>HANA</strong>.<br />
● <strong>SAP</strong> <strong>HANA</strong> as a Development Platform [page 16] describes the main developer scenarios, the development<br />
process and the development environment.<br />
● Setting Up Your Application [page 34] describes how to get started developing <strong>SAP</strong> <strong>HANA</strong> applications.<br />
Most of the remaining chapters explain how to develop various <strong>SAP</strong> <strong>HANA</strong> development objects.<br />
Audience<br />
Note: Application development with <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) is<br />
currently only available as an <strong>SAP</strong>-led project solution, for pre-approved customers and partners. This<br />
applies to server-side JavaScript programming, support for ODATA and XMLA, Web server features and<br />
the Web application development environment. For more information, see <strong>SAP</strong> Note 1779803.<br />
This guide is aimed at two developer roles:<br />
● Modeler: This person, often a business/data analyst or database expert, is concerned with the definition of<br />
the model and schemas that will be used in <strong>SAP</strong> <strong>HANA</strong>, the specification and definition of tables, views,<br />
primary keys, indexes, partitions and other aspects of the layout and inter-relationship of the data in <strong>SAP</strong><br />
<strong>HANA</strong>.<br />
The data modeler is also concerned with designing and defining authorization and access control, through the<br />
specification of privileges, roles and users.<br />
The modeler generally uses the Administration Console and Modeler perspectives and tools of the <strong>SAP</strong> <strong>HANA</strong><br />
studio.<br />
● Application Programmer: The programmer is concerned with building <strong>SAP</strong> <strong>HANA</strong> applications, which could<br />
8<br />
take many forms but are designed based on the model-view-controller architecture. Programmers develop<br />
the code for:<br />
○ View, which could run inside a browser or on a mobile device<br />
○ Controller, which typically runs in the context of an application server<br />
○ Model, which interacts closely with the data model, performs efficient queries, and may be developed to<br />
run within the <strong>SAP</strong> <strong>HANA</strong> data engine, using embedded procedures or libraries<br />
The programmer generally uses the <strong>SAP</strong> <strong>HANA</strong> Development perspective and tools of the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Overview
2 <strong>SAP</strong> <strong>HANA</strong><br />
<strong>SAP</strong> <strong>HANA</strong> is an in-memory data platform that is deployable as an appliance or in the cloud. At its core, it is an<br />
innovative in-memory relational database management system that makes full use of the capabilities of current<br />
hardware to increase application performance, to reduce cost of ownership, and to enable new scenarios and<br />
applications that were not possible before.<br />
With <strong>SAP</strong> <strong>HANA</strong>, you have the opportunity to build applications that integrate the business control logic and the<br />
database layer with unprecedented performance. As a developer, one of the key questions is how you can<br />
minimize data movements. The more you can do directly on the data in memory next to the CPUs, the better the<br />
application will perform.<br />
2.1 The <strong>SAP</strong> <strong>HANA</strong> In-Memory Database<br />
<strong>SAP</strong> <strong>HANA</strong> was designed to run on modern, distributed computers built out of multi-core CPUs (multiple CPUs on<br />
one chip) with fast communication between processor cores, and containing terabytes of main memory. With<br />
<strong>SAP</strong> <strong>HANA</strong>, all data is available in main memory, which completely avoids the performance penalty of disk I/O.<br />
Either disk or solid-state drives are still required for permanent persistency in the event of a power failure or some<br />
other catastrophe. This does not slow down performance, however, because the required backup operations to<br />
disk can take place asynchronously as a background task.<br />
2.1.1 Columnar Data Storage<br />
A database table is conceptually a two-dimensional data structure organized in rows and columns. Computer<br />
memory, in contrast, is organized as a linear structure. A table can be represented in row-order or column-order.<br />
A row-oriented organization stores a table as a sequence of records. Conversely, in column storage the entries of<br />
a column are stored in contiguous memory locations. <strong>SAP</strong> <strong>HANA</strong> supports both, but is particularly optimized for<br />
column-order storage.<br />
Columnar data storage allows highly efficient compression. Especially if a column is sorted, there will normally be<br />
repeated adjacent values. <strong>SAP</strong> <strong>HANA</strong> employs highly efficient compression methods, such as run-length<br />
encoding, cluster coding and dictionary coding. With dictionary encoding, columns are stored as sequences of bitcoded<br />
integers. That means that a check for equality can be executed on the integers (for example during scans<br />
or join operations). This is much faster than comparing, for example, string values.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong><br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 9
Columnar storage, in many cases, eliminates the need for additional index structures. Storing data in columns is<br />
functionally similar to having a built-in index for each column. The column scanning speed of the in-memory<br />
column store and the compression mechanisms – especially dictionary compression – allow read operations with<br />
very high performance. In many cases it will not be required to have additional indexes. Eliminating additional<br />
indexes reduces complexity and eliminates effort for defining and maintaining metadata.<br />
2.1.2 Parallel Processing<br />
<strong>SAP</strong> <strong>HANA</strong> was designed from the ground up to perform its basic calculations (such as analytic joins, scans and<br />
aggregations) in parallel, often using hundreds of cores at the same time, fully utilizing the available computing<br />
resources of distributed systems.<br />
With columnar data, operations on single columns, such as searching or aggregations, can be implemented as<br />
loops over an array stored in contiguous memory locations. Such an operation has high spatial locality and can<br />
efficiently be executed in the CPU cache. With row-oriented storage, the same operation would be much slower<br />
because data of the same column is distributed across memory and the CPU is slowed down by cache misses.<br />
Compressed data can be loaded into the CPU cache faster. This is because the limiting factor is the data transport<br />
between memory and CPU cache, and so the performance gain will exceed the additional computing time needed<br />
for decompression.<br />
Column-based storage also allows execution of operations in parallel using multiple processor cores. In a column<br />
store, data is already vertically partitioned. This means that operations on different columns can easily be<br />
processed in parallel. If multiple columns need to be searched or aggregated, each of these operations can be<br />
assigned to a different processor core. In addition, operations on one column can be parallelized by partitioning<br />
the column into multiple sections that can be processed by different processor cores.<br />
2.1.3 Simplifying Applications<br />
Traditional business applications often use materialized aggregates to increase performance. These aggregates<br />
are computed and stored either after each write operation on the aggregated data, or at scheduled times. Read<br />
operations read the materialized aggregates instead of computing them each time they are required.<br />
10<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong>
With a scanning speed of several gigabytes per millisecond, <strong>SAP</strong> <strong>HANA</strong> makes it possible to calculate aggregates<br />
on large amounts of data on-the-fly with high performance. This eliminates the need for materialized aggregates<br />
in many cases, simplifying data models, and correspondingly the application logic. Furthermore, with on-the fly<br />
aggregation, the aggregate values are always up-to-date unlike materialized aggregates that may be updated only<br />
at scheduled times.<br />
2.2 <strong>SAP</strong> <strong>HANA</strong> Database Architecture<br />
A running <strong>SAP</strong> <strong>HANA</strong> system consists of multiple communicating processes (services). The following shows the<br />
main <strong>SAP</strong> <strong>HANA</strong> database services in a classical application context.<br />
Such traditional database applications use well-defined interfaces (for example, ODBC and JDBC) to<br />
communicate with the database management system functioning as a data source, usually over a network<br />
connection. Often running in the context of an application server, these traditional applications use Structured<br />
Query Language (SQL) to manage and query the data stored in the database.<br />
The main <strong>SAP</strong> <strong>HANA</strong> database management component is known as the index server. The index server contains<br />
the actual data stores and the engines for processing the data. The index server processes incoming SQL or MDX<br />
statements in the context of authenticated sessions and transactions.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong><br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 11
The <strong>SAP</strong> <strong>HANA</strong> database has its own scripting language named SQLScript. The motivation for SQLScript is to<br />
embed data-intensive application logic into the database. Classical applications tend to offload only very limited<br />
functionality into the database using SQL. This results in extensive copying of data from and to the database, and<br />
in programs that slowly iterate over huge data loops and are hard to optimize and parallelize. SQLScript is based<br />
on side-effect free functions that operate on tables using SQL queries for set processing, and is therefore<br />
parallelizable over multiple processors.<br />
In addition to SQLScript, <strong>SAP</strong> <strong>HANA</strong> supports a framework for the installation of specialized and optimized<br />
functional libraries, which are tightly integrated with different data engines of the index server. Two of these<br />
functional libraries are the <strong>SAP</strong> <strong>HANA</strong> Business Function Library (BFL) and the <strong>SAP</strong> <strong>HANA</strong> Predictive Analytics<br />
Library (PAL). BFL and PAL functions can be called directly from within SQLScript.<br />
<strong>SAP</strong> <strong>HANA</strong> also supports the development of programs written in the popular statistics language R.<br />
SQL and SQLScript are implemented using a common infrastructure of built-in data engine functions that have<br />
access to various meta definitions, such as definitions of relational tables, columns, views, and indexes, and<br />
definitions of SQLScript procedures. This metadata is stored in one common catalog.<br />
The database persistence layer is responsible for durability and atomicity of transactions. It ensures that the<br />
database can be restored to the most recent committed state after a restart and that transactions are either<br />
completely executed or completely undone.<br />
The index server uses the preprocessor server for analyzing text data and extracting the information on which the<br />
text search capabilities are based. The name server owns the information about the topology of a <strong>SAP</strong> <strong>HANA</strong><br />
system. In a distributed system, the name server knows where the components are running and which data is<br />
located on which server. The statistics server collects information about status, performance and resource<br />
consumption from the other servers in the system. Monitoring clients, such as the <strong>SAP</strong> <strong>HANA</strong> studio, access the<br />
statistics server to get the status of various alert monitors. The statistics server also provides a history of<br />
measurement data for further analysis.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> SQLScript Reference<br />
<strong>SAP</strong> <strong>HANA</strong> Business Function Library (BFL) Reference<br />
<strong>SAP</strong> <strong>HANA</strong> Predictive Analysis Library (PAL) Reference<br />
<strong>SAP</strong> <strong>HANA</strong> R Integration <strong>Guide</strong><br />
2.3 <strong>SAP</strong> <strong>HANA</strong> Extended Application Services<br />
Traditional database applications use interfaces such as ODBC and JDBC with SQL to manage and query their<br />
data. The following illustrates such applications using the common Model-View-Controller (MVC) development<br />
architecture.<br />
12<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong>
<strong>SAP</strong> <strong>HANA</strong> greatly extends the traditional database server role. <strong>SAP</strong> <strong>HANA</strong> functions as a comprehensive<br />
platform for the development and execution of native data-intensive applications that run efficiently in <strong>SAP</strong> <strong>HANA</strong>,<br />
taking advantage of its in-memory architecture and parallel execution capabilities.<br />
By restructuring your application in this way, not only do you gain from the increased performance due to the<br />
integration with the data source, you can effectively eliminate the overhead of the middle-tier between the userinterface<br />
(the view) and the data-intensive control logic, as shown in the following figure.<br />
In support of this data-integrated application paradigm, <strong>SAP</strong> <strong>HANA</strong> Extended Application Services provides a<br />
comprehensive set of embedded services that provide end-to-end support for Web-based applications. This<br />
includes a lightweight web server, configurable OData support, server-side JS execution and, of course, full<br />
access to SQL and SQLScript.<br />
These <strong>SAP</strong> <strong>HANA</strong> Extended Application Services are provided by the <strong>SAP</strong> <strong>HANA</strong> XS server, which provides<br />
lightweight application services that are fully integrated into <strong>SAP</strong> <strong>HANA</strong>. It allows clients to access the <strong>SAP</strong> <strong>HANA</strong><br />
system via HTTP. Controller applications can run completely natively on <strong>SAP</strong> <strong>HANA</strong>, without the need for an<br />
additional external application server.The following shows the <strong>SAP</strong> <strong>HANA</strong> XS server as part of the <strong>SAP</strong> <strong>HANA</strong><br />
system.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong><br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 13
The application services can be used to expose the database data model, with its tables, views and database<br />
procedures, to clients. This can be done in a declarative way using OData services or by writing native applicationspecific<br />
code that runs in the <strong>SAP</strong> <strong>HANA</strong> context . Also, you can use <strong>SAP</strong> <strong>HANA</strong> XS to build dynamic HTML5 UI<br />
applications.<br />
In addition to exposing the data model, <strong>SAP</strong> <strong>HANA</strong> XS also hosts system services that are part of the <strong>SAP</strong> <strong>HANA</strong><br />
system. The search service is an example of such a system application. No data is stored in the <strong>SAP</strong> <strong>HANA</strong> XS<br />
server itself. To read tables or views, to modify data or to execute SQLScript database procedures and<br />
calculations, it connects to the index server (or servers, in case of a distributed system).<br />
Related Links<br />
Note: Application development with <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) is<br />
currently only available as an <strong>SAP</strong>-led project solution, for pre-approved customers and partners. This<br />
applies to server-side JavaScript programming, support for ODATA and XMLA, Web server features and<br />
the Web application development environment. For more information, see <strong>SAP</strong> Note 1779803.<br />
Building UIs with <strong>SAP</strong>UI5 [page 229]<br />
This section provides introductory information about UI development toolkit for HTML5.<br />
Enabling Search [page 235]<br />
With a <strong>SAP</strong> <strong>HANA</strong> database, your users will want to search tables and views much like they would when<br />
searching for information on the Internet. In <strong>SAP</strong> <strong>HANA</strong>, you can either directly query data using SQL queries<br />
or you can build search apps using a UI toolkit.<br />
14<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong>
2.4 Refactoring <strong>SAP</strong> <strong>HANA</strong> Based Applications<br />
The possibility to run application-specific code in <strong>SAP</strong> <strong>HANA</strong> raises the question: What kind of logic should run<br />
where? Clearly, data-intensive and model-based calculations must be close to the data and, therefore, need to be<br />
executed in the index server, for instance, using SQLScript or the code of the specialized functional libraries.<br />
The presentation (view) logic runs on the client – for example, as an HTML5 application in a Web browser or on a<br />
mobile device.<br />
Native application-specific code, supported by <strong>SAP</strong> <strong>HANA</strong> Extended Application Services, can be used to provide<br />
a thin layer between the clients on one side, and the views, tables and procedures in the index server on the other<br />
side. Typical applications contain, for example, control flow logic based on request parameters, invoke views and<br />
stored procedures in the index server, and transform the results to the response format expected by the client.<br />
Such applications can also send emails and consume external HTTP-based services.<br />
The communication between the <strong>SAP</strong> <strong>HANA</strong> XS server and index server is optimized for high performance.<br />
However, performance is not the only reason why the <strong>SAP</strong> <strong>HANA</strong> XS server was integrated into <strong>SAP</strong> <strong>HANA</strong>. It also<br />
leads to simplified administration and a better development experience.<br />
The <strong>SAP</strong> <strong>HANA</strong> XS server completes <strong>SAP</strong> <strong>HANA</strong> to make it a comprehensive development platform. With the <strong>SAP</strong><br />
<strong>HANA</strong> XS server, developers can write <strong>SAP</strong> <strong>HANA</strong>-based applications that cover all server-side aspects, such as<br />
tables and database views, database procedures, server-side control logic, integration with external systems, and<br />
provisioning of HTTP-based services. The integration of the <strong>SAP</strong> <strong>HANA</strong> XS server into the <strong>SAP</strong> <strong>HANA</strong> system also<br />
helps to reduce cost of ownership, as all servers are installed, operated and updated as one system.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong><br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 15
3 <strong>SAP</strong> <strong>HANA</strong> as a Development<br />
Platform<br />
To simplify and support the development of <strong>HANA</strong> Based applications, <strong>SAP</strong> <strong>HANA</strong> serves as the integrated<br />
development environment (IDE) for developing and delivering these <strong>SAP</strong> <strong>HANA</strong> applications.<br />
Built around the Eclipse-based <strong>SAP</strong> <strong>HANA</strong> studio the <strong>SAP</strong> <strong>HANA</strong> IDE supports integrated and collaborative<br />
development, debugging and deployment of applications that use native database procedures for data<br />
processing, server-side JavaScript for control and an HTML5 SDK for the development of user interface<br />
representation.<br />
The design-time environment's central component is the <strong>SAP</strong> <strong>HANA</strong> repository, which stores and manages all<br />
design-time objects. The following figure illustrates the principle of co-development with <strong>SAP</strong> <strong>HANA</strong>.<br />
Using the <strong>HANA</strong> studio on your workstation, you design and create development objects such as data models or<br />
server-side code files, and then store, manage and share them with other developers, by interacting with the <strong>SAP</strong><br />
<strong>HANA</strong> repository. The repository enables teams to work together on a set of development objects, and ultimately<br />
turn them into runtime objects which can be used by clients or other applications. The repository provides the<br />
basis for concepts like namespaces (through packages), transport and delivery support.<br />
3.1 <strong>Developer</strong> Scenarios<br />
The possibility to run application specific code in <strong>SAP</strong> <strong>HANA</strong> creates several possibilities for developing <strong>SAP</strong><br />
<strong>HANA</strong> based applications, representing various integration scenarios, and corresponding development<br />
processes.<br />
Broadly, we distinguish <strong>SAP</strong> <strong>HANA</strong> based applications into two broad categories:<br />
● Web-based scenarios that take full advantage of the <strong>SAP</strong> <strong>HANA</strong> Extended Application Services. In these<br />
scenarios, clients access <strong>SAP</strong> <strong>HANA</strong> data using standard OData or XMLA interfaces, or directly use a Webbased<br />
GUI that was developed using the <strong>SAP</strong>GUI5 toolkit, and that uses custom-developed server-side<br />
JavaScript, as well as native SQLScript procedures.<br />
● Traditional client-based scenarios, where an external application accesses the <strong>SAP</strong> <strong>HANA</strong> data model (tables,<br />
analytic views, etc.) via client interfaces such as ODBC, ODBO and JDBC, and only uses SQL and native<br />
SQLScript procedures.<br />
16<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
In either case, as a developer you need to understand the <strong>SAP</strong> <strong>HANA</strong> development environment, which enables<br />
you to design and develop your data and analytical models, and your other <strong>HANA</strong>-based development objects in<br />
the form of portable and deployable delivery units.<br />
Common activities include:<br />
Table 1: Common Activities<br />
Activity More Information<br />
Setting up your development environment. Setting Up Your Application [page 34]<br />
Setting up your schema and tables. Setting Up the Persistence Model [page 74]<br />
Setting up views of your data. Setting Up the Analytic Model [page 92]<br />
Developing procedures for data-intensive logic. Developing Procedures [page 158]<br />
Setting up roles and authorizations. i031349596025517.ditamap<br />
Managing the delivery of your application. <strong>SAP</strong> <strong>HANA</strong> Delivery Units [page 348]<br />
For these activites, you will want to keep handy the following references:<br />
● <strong>SAP</strong> <strong>HANA</strong> SQL Reference, to help you writing SQL statements within procedures and from your server-side<br />
JavaScript.<br />
● <strong>SAP</strong> <strong>HANA</strong> SQLScript Reference, to help you if you are writing procedures.<br />
The next two sections describes the main scenarios and what activities you may need to perform for them.<br />
3.1.1 Scenario: Developing Native <strong>SAP</strong> <strong>HANA</strong> Applications<br />
Here, you want to create a Web-based scenario that takes full advantage of <strong>SAP</strong> <strong>HANA</strong> Extended Application<br />
Services. In this scenario, clients access <strong>SAP</strong> <strong>HANA</strong> data using standard OData or XMLA interfaces, or directly use<br />
a Web-based GUI that was developed using the <strong>SAP</strong>GUI5 toolkit, and that uses custom-developed server-side<br />
JavaScript, as well as native SQLScript procedures.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 17
For this scenario, you may need to perform the following activities:<br />
Table 2: Developing Native <strong>SAP</strong> <strong>HANA</strong> Applications<br />
Activity More Information<br />
Develop server-side JavaScript for control logic. Writing Server-Side JavaScript Applications [page<br />
Define OData data interfaces. Data Access with OData in <strong>SAP</strong> <strong>HANA</strong> XS [page 164]<br />
Define XMLA data interfaces Data Access with XMLA in <strong>SAP</strong> <strong>HANA</strong> XS [page 201]<br />
How to build HTML pages with <strong>SAP</strong>UI5. Building UIs with <strong>SAP</strong>UI5 [page 229]<br />
You will also want to keep handy the following references:<br />
● <strong>SAP</strong> <strong>HANA</strong> SQL Reference, to help you write SQL statements within procedures and from your server-side<br />
JavaScript.<br />
● <strong>SAP</strong> <strong>HANA</strong> XS JavaScript Reference, to help you use the <strong>SAP</strong> <strong>HANA</strong> XS JavaScript API.<br />
212]<br />
For a list of all references, see <strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> References [page 373].<br />
3.1.2 Scenario: Using Database Client Interfaces<br />
Here, you want to build an application outside of <strong>SAP</strong> <strong>HANA</strong>, for example, within <strong>SAP</strong> NetWeaver, that accesses<br />
the <strong>SAP</strong> <strong>HANA</strong> data model (for example, tables and analytic views) via client interfaces such as ODBC, ODBO and<br />
JDBC, and only uses SQL and native SQLScript procedures.<br />
18<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
For this scenario, you may need to perform the following activities:<br />
Table 3: Using Database Client Interfaces<br />
Activity More Information<br />
Installing and using the <strong>SAP</strong> <strong>HANA</strong> client interfaces Using Database Client Interfaces [page 355]<br />
Developing procedures for data-intensive logic. Developing Procedures [page 158]<br />
You will also want to keep handy several references:<br />
● <strong>SAP</strong> <strong>HANA</strong> SQL Reference, to help you write SQL statements.<br />
For information on MDX in <strong>SAP</strong> <strong>HANA</strong>, see MDX Functions [page 204].<br />
● <strong>SAP</strong> <strong>HANA</strong> SQLScript Reference, to help you if you are writing procedures.<br />
For a list of all references, see <strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> References [page 373].<br />
3.2 Development Objects<br />
The design-time building blocks of your <strong>SAP</strong> <strong>HANA</strong> applications are called development objects. Some of these<br />
development objects, such as projects and packages, are concepts that help you structure your application.<br />
Others, like schemas, table definitions, analytical and attribute views, help you organize the structure of your data.<br />
Procedures and server-side JavaScript code are the backbone of the <strong>SAP</strong> <strong>HANA</strong> application. Other types of<br />
development objects help you control the access to runtime objects.<br />
Understanding the different development objects and their use is one of the main objectives of this guide.<br />
The following are the building blocks for an <strong>SAP</strong> <strong>HANA</strong> application, showing the file extension and where to get<br />
information for building it:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 19
Table 4: Application Building Blocks<br />
Object Description File Extension More Information<br />
Structure<br />
Project An Eclipse project for developing your<br />
application or part of an application.<br />
The .project file can be stored in the <strong>SAP</strong><br />
<strong>HANA</strong> repository.<br />
Package A container in the repository for<br />
development objects.<br />
Modeling Data<br />
Schema A database schema for organizing database<br />
objects.<br />
.project <strong>SAP</strong> <strong>HANA</strong> Studio Projects<br />
Packages are<br />
represented by<br />
folders.<br />
[page 39]<br />
Maintaining Repository<br />
Packages [page 42]<br />
.hdbschema Schema [page 75]<br />
Table A database table. .hdbtable Tables [page 76]<br />
SQL View A virtual table based on a SQL query. .hdbview SQL Views [page 80]<br />
Attribute,<br />
Analytic and<br />
Calculation<br />
View<br />
A view created with modeling tools and<br />
designed to model a business use case.<br />
Decision Table A database table used to define business<br />
rules, for example, for validating data.<br />
Analytic<br />
Privilege<br />
A set of rules that restricts users to seeing<br />
only a subset of data in a table or view.<br />
Sequence A set of unique numbers, for example, for<br />
use as primary keys for a specific table.<br />
Procedure A database function for performing<br />
complex and data-intensive business logic<br />
that cannot be performed with standard<br />
SQL.<br />
Web Access<br />
Application<br />
Descriptor<br />
Application<br />
Access File<br />
Application<br />
Privilege<br />
20<br />
A file in a repository package that defines a<br />
root folder of a native <strong>SAP</strong> <strong>HANA</strong><br />
application. All files in that package are<br />
available to be called via URL.<br />
A file that defines permissions for a native<br />
<strong>SAP</strong> <strong>HANA</strong> application, that is, permissions<br />
for accessing and running objects in the<br />
package.<br />
A file that defines a privilege related to an<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
Created with the<br />
Navigator view.<br />
Setting Up the Analytic<br />
Model [page 92]<br />
Creating Decision Tables<br />
[page 133]<br />
Creating Analytic Privileges<br />
[page 341]<br />
.hdbsequence Sequences [page 78]<br />
.procedure Developing Procedures<br />
[page 158]<br />
.xsapp Creating the Application<br />
Descriptors [page 49]<br />
.xsaccess Enabling Access to <strong>SAP</strong><br />
<strong>HANA</strong> XS Application<br />
Packages [page 57]<br />
.xsprivileges The Application-Privileges<br />
File [page 59]<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
Object Description File Extension More Information<br />
Server-Side<br />
JavaScript<br />
Code<br />
Server-Side<br />
JavaScript<br />
Library<br />
OData<br />
Descriptor<br />
XMLA<br />
Descriptor<br />
SQL Connection<br />
Configuration<br />
Other<br />
application, for example, the right to start or<br />
administer the application.<br />
JavaScript code that can run in <strong>SAP</strong> <strong>HANA</strong><br />
Extended Application Services and that can<br />
be accessed via URL.<br />
JavaScript code that can run in <strong>SAP</strong> <strong>HANA</strong><br />
Extended Application Services but cannot<br />
be accessed via URL. The code can be<br />
imported into an .xsjs code file.<br />
A file that defines an OData service that<br />
exposes <strong>SAP</strong> <strong>HANA</strong> data.<br />
A file that defines an XMLA service that<br />
exposes <strong>SAP</strong> <strong>HANA</strong> data<br />
A file that enables execution of SQL<br />
statements from inside server-side<br />
JavaScript code with credentials that are<br />
different than those of the requesting user.<br />
.xsjs Writing Server-Side<br />
JavaScript Applications<br />
[page 218]<br />
.xsjslib<br />
.xsodata Data Access with OData in<br />
<strong>SAP</strong> <strong>HANA</strong> XS [page 164]<br />
.xsxmla Data Access with XMLA in<br />
<strong>SAP</strong> <strong>HANA</strong> XS [page 201]<br />
.xssqlcc The SQL Connection<br />
Configuration File [page<br />
222]<br />
Role A file that defines an <strong>SAP</strong> <strong>HANA</strong> role. .hdbrole Creating Roles in the<br />
Repository [page 324]<br />
Search Rule Set A file that defines a set of rules for use with<br />
fuzzy searches. The rules help decide what<br />
is a valid match in a search.<br />
Resource<br />
Bundle<br />
3.3 Repository<br />
A file for defining translatable UI texts for an<br />
application.<br />
.searchruleset Search Rules [page 301]<br />
.hdbtextbundle Creating an <strong>SAP</strong>UI5<br />
Application [page 230]<br />
The <strong>SAP</strong> <strong>HANA</strong> repository is the design-time storage system for development objects and is built into <strong>SAP</strong> <strong>HANA</strong>.<br />
The repository is the source control for all your development work on <strong>SAP</strong> <strong>HANA</strong>. You can add objects to the<br />
repository, update the objects, publish the objects, and compile these design-time objects into runtime objects.<br />
The repository supports the following:<br />
● Version Control<br />
● Sharing of objects between multiple developers<br />
● Transport<br />
The repository manages all development objects. You can browse the repository for a specific system with the<br />
<strong>SAP</strong> <strong>HANA</strong> Repositories view.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 21
Packages<br />
Within the repository, development objects are managed as files within packages. Packages enable you to:<br />
● Create namespaces, so you can uniquely identify development objects.<br />
● Group objects that logically belong together.<br />
● Provide containers for your objects so you can easily insert relevant objects into delivery units and transport<br />
them.<br />
● Assign permissions at the package level.<br />
You might create a top-level package for your company, and then a subpackage for each project, and then<br />
subpackages for parts of your project, for example, a subpackage for your HTML files, another for server-side<br />
JavaScript files, and so forth.<br />
Workspaces<br />
When working with development objects, you need to retrieve them from the repository, work on them on your<br />
workstation, and then return them to the repository. To make this simpler, the <strong>SAP</strong> <strong>HANA</strong> studio enables you to<br />
create a repository workspace, which establishes a link between two locations:<br />
● The repository of the <strong>SAP</strong> <strong>HANA</strong> system where you wish to maintain the development object files of your<br />
projects (in the form of a package hierarchy).<br />
● A directory/folder on your workstation where you checkout these project files while you are working on them.<br />
Working with Objects<br />
When creating development objects, the following is the workflow:<br />
1. Create a project.<br />
2. Share the project to associate it with a workspace, and thus a specific <strong>SAP</strong> <strong>HANA</strong> system. Shared projects,<br />
once they are activated, are available for import by other members of the application-development team.<br />
3. Create a new object file within the project, and save it to your workstation. Depending on the extension of the<br />
file you create, you may use a dedicated editor for that type of object, for example, a JavaScript editor<br />
for .xsjs files.<br />
4. Commit the file.<br />
22<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
Committing the file saves it in the repository, but the object is inactive and cannot be run, and only you can<br />
see it.<br />
5. Activate the file.<br />
Activating a file does the following:<br />
○ Publishes the file so others can see it.<br />
○ Adds the previously active version of the file to the history. The repository maintains a history of changes<br />
to the file.<br />
○ Validates the file and compiles it or exposes it as a runtime object.<br />
The design-time object is now active.<br />
Related Links<br />
Setting Up Your Application [page 34]<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the design-time artifacts that make up your<br />
application are stored in the repository like files in a file system. You first choose a root folder for your<br />
application-development activities, and within this folder you create additional subfolders to organize the<br />
applications and the application content according to your own requirements.<br />
3.4 <strong>SAP</strong> <strong>HANA</strong> Studio<br />
The <strong>SAP</strong> <strong>HANA</strong> studio is an Eclipse-based development and administration tool for working with <strong>SAP</strong> <strong>HANA</strong>,<br />
including creating projects, creating development objects, and deploying them to <strong>SAP</strong> <strong>HANA</strong>. As a developer, you<br />
may want to also perform some administrative tasks, such as configuring and monitoring the system.<br />
There are several key Eclipse perspectives that you will use while developing:<br />
● Modeler: Used for creating various types of views and analytical privileges.<br />
● <strong>SAP</strong> <strong>HANA</strong> Development: Used for programming applications, that is, creating development objects that<br />
access or update the data models, such as server-side JavaScript or HTML files.<br />
● Debug: Used to debug code, such as server-side JavaScript or SQLScript.<br />
● Administration: Used to monitor the system and change settings.<br />
To open a perspective, go to Window Open Perspective , or select on the toolbar.<br />
3.4.1 Modeler Perspective<br />
The Modeler perspective is used to define your analytic model by creating various types of views.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 23
The perspective contains the following main areas:<br />
● Navigator View: A view of the database objects, that is, those objects you create from the Modeler<br />
perspective.<br />
● Quick Launch Area: A collection of shortcuts for performing the most common modeling tasks. If you close<br />
the Quick Launch tab, you can reopen it by selecting Help Quick Launch .<br />
Navigator View<br />
The Navigator view shows a view of the database objects in <strong>SAP</strong> <strong>HANA</strong>, both those that have been activated and<br />
those objects you created and have not activated yet.<br />
The view is divided into the following main sections:<br />
24<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
● Security: Contains the roles and users defined for this system.<br />
● Catalog: Contains the database objects that have been activated. The objects are divided into schemas, which<br />
is a way to organize activated database objects.<br />
● Content: Contains design-time database objects, both those that have been activated and those not activated.<br />
If you want to see other development objects, use the <strong>SAP</strong> <strong>HANA</strong> Repositories view.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Repositories View [page 26]<br />
3.4.2 <strong>SAP</strong> <strong>HANA</strong> Development Perspective<br />
The <strong>SAP</strong> <strong>HANA</strong> Development perspective is where you will do most of your programming work, creating projects,<br />
associating them to <strong>SAP</strong> <strong>HANA</strong> systems, creating development objects, and deploying them.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 25
The perspective contains the following main areas:<br />
● Development Objects: Several views for browsing your development objects: the objects on your workstation,<br />
and the objects in the repository of the <strong>SAP</strong> <strong>HANA</strong> system you are working with.<br />
● Editors: Specialized editors for working with different types of development objects.<br />
<strong>SAP</strong> <strong>HANA</strong> Repositories View<br />
The <strong>SAP</strong> <strong>HANA</strong> Repositories view enables you to browse the repository of a specific <strong>SAP</strong> <strong>HANA</strong> system, viewing<br />
the package hierarchy and to download files to your workstation.<br />
26<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
The view essentially is a list of repository workspaces that you have created for developing on various systems.<br />
Generally, you create a workspace, check out files from the repository, and then do most of your development<br />
work in the Project Explorer.<br />
If you are creating a project from scratch, you do not need anything from this view, except to see the hierarchy of<br />
the repository. You create the project in the Project Explorer.<br />
Project Explorer View<br />
The Project Explorer is the standard Project Explorer view in Eclipse, which shows you the development files<br />
located on your workstation.<br />
Here you can create files, edit files, and deploy them to the repository.<br />
Working with the Repository<br />
To work with the repository, you need to either:<br />
● Share your project with the repository via a workspace. Sharing a project associates it with a <strong>SAP</strong> <strong>HANA</strong><br />
system, so that files within the project can be added to the repository on that system.<br />
● Check out an existing package in the repository from a workspace. This creates copies on your workstation of<br />
the package, its subpackages and their objects.<br />
Team Menu<br />
You can interact with the repository by right-clicking on a file or project (in the Project Explorer view) or package<br />
(in the <strong>SAP</strong> <strong>HANA</strong> Repositories view), and selecting an option from the Team menu.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 27
You can perform the following on a file, folder or project in the Project Explorer view, that is, development objects<br />
that you are working on and located on your workstation:<br />
Table 5: Repository Actions in Project Explorer (project, folder, or file)<br />
Action Description<br />
Commit<br />
Saves the object to the repository.<br />
The object (or changes to the object) are only visible to you. There is no versioning of<br />
committed objects; the repository stores only the latest committed changes.<br />
Activate Makes the development object active, and does the following:<br />
28<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
● Publishes the object so it is visible to others.<br />
● Compiles the object into runtime objects.<br />
● Deploys the runtime object.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
Action Description<br />
● Creates a new version of the design-time object.<br />
Check Simulates activation of the object in order to check if the object is valid and can be<br />
activated.<br />
Checkout Retrieves the latest version of the object from the repository.<br />
Revert Removes all your committed changes (inactive object) with the latest version of the object<br />
Share/Unshare<br />
(project only)<br />
that was activated.<br />
Associates a project with a specific <strong>SAP</strong> <strong>HANA</strong> system, so that files within the project can<br />
be added and updated on the repository on that system. For more information, see Using<br />
<strong>SAP</strong> <strong>HANA</strong> Projects [page 37].<br />
The following options are available for files only.<br />
Show Local History Shows a history of all versions of your object saved on your workstation. This is the Eclipse<br />
Show History<br />
local history feature.<br />
Shows a history of all the versions of the object that were activated in the repository.<br />
Currently, you can only view a list of versions.<br />
You can perform the following on a package and file in the <strong>SAP</strong> <strong>HANA</strong> Repositories view:<br />
Table 6: Repository Actions in <strong>SAP</strong> <strong>HANA</strong> Repositories (package or file)<br />
Action Description<br />
Checkout (package<br />
only)<br />
Checkout and<br />
Import Projects<br />
(package only)<br />
Retrieves the latest version of the objects from the repository in this package and its<br />
subpackages.<br />
Retrieves the latest version of the objects from the repository in this package, and imports<br />
a project into the <strong>SAP</strong> <strong>HANA</strong> studio. For more information, see Using <strong>SAP</strong> <strong>HANA</strong> Projects<br />
[page 37].<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 29
Action Description<br />
Show History (file<br />
only)<br />
Status of Development Objects<br />
Shows a history of all the versions of the object that were activated in the repository.<br />
Each object displayed in your project within the Project Explorer view is shown with an icon that indicates its<br />
status.<br />
Table 7: Status of Development Objects<br />
Icon Description<br />
The file is not committed. You made a change to the file and saved it to your workstation, but have<br />
not yet committed the changes to the repository.<br />
The file is committed.<br />
The file is activated.<br />
3.4.3 Debug Perspective<br />
The Debug perspective in the <strong>SAP</strong> <strong>HANA</strong> studio is the standard Eclipse Debug perspective, enabling you to start<br />
debug sessions, create breakpoints and watch variables.<br />
In the <strong>SAP</strong> <strong>HANA</strong> studio, the debug tools have been enhanced to let you also debug <strong>SAP</strong> <strong>HANA</strong> code, both serverside<br />
JavaScript (.xsjs files) and SQLScript code (.procedure files). The following shows the tools available in<br />
the Debug perspective and how it is organized:<br />
30<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
● Debug Session: The debug sessions that have been started<br />
● Watch: Breakpoints and variables to watch<br />
● Code: Code files that you have opened<br />
Related Links<br />
Debugging JavaScript [page 225]<br />
<strong>SAP</strong> <strong>HANA</strong> studio enables you to debug XS JavaScript files, including setting breakpoints and inspecting<br />
variables.<br />
Debugging SQLScript [page 161]<br />
The <strong>SAP</strong> <strong>HANA</strong> SQLScript debugger allows you to debug and analyze procedures. In a debug session, your<br />
procedures will be executed in a serial mode, not in parallel (not-optimized). This allows you to test the<br />
correctness of the procedure logic and is not for evaluating the performance.<br />
3.4.4 Administration Console Perspective<br />
The Administration Console perspective enables you to configure the <strong>SAP</strong> <strong>HANA</strong> server so that you can do your<br />
development work. For example, when debugging, the debug port must be opened and debugging enabled, which<br />
is done by setting configuration parameters within the administration console.<br />
The Administration Console perspective displays the Navigator view, for adding or selecting systems, and the<br />
administration console, where you can monitor and configure the system. Configuration parameters can viewed<br />
and changed from the Configuration tab.<br />
Note: You may need additional permissions to work with the administration console.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 31
If the console is closed, you can open it by clicking the Administration icon in the Navigator view.<br />
3.5 <strong>Get</strong>ting Started<br />
Before starting development work in the <strong>SAP</strong> <strong>HANA</strong> studio, make sure to have the following:<br />
● An installation of the <strong>SAP</strong> <strong>HANA</strong> studio on your workstation.<br />
● A live <strong>SAP</strong> <strong>HANA</strong> system to which to connect.<br />
● A user on the <strong>SAP</strong> <strong>HANA</strong> server that has at least the following roles or their equivalent:<br />
32<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform
○ MODELING<br />
○ CONTENT_ADMIN<br />
3.5.1 Adding a System<br />
To develop applications, you must first make a connection from your <strong>SAP</strong> <strong>HANA</strong> studio to an <strong>SAP</strong> <strong>HANA</strong> system.<br />
1. In the Navigator view, right-click anywhere in the view and select Add System.<br />
2. In the System window, enter the host name, instance number, and a description for the <strong>SAP</strong> <strong>HANA</strong> system<br />
you want to add.<br />
3. Select Next.<br />
4. Enter a user name and password, and select Finish.<br />
The Navigator view includes a new top-level node for the system. You can now create a repository workspace for<br />
this system so you can start to develop objects to run in it.<br />
Related Links<br />
Setting Up Your Application [page 34]<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the design-time artifacts that make up your<br />
application are stored in the repository like files in a file system. You first choose a root folder for your<br />
application-development activities, and within this folder you create additional subfolders to organize the<br />
applications and the application content according to your own requirements.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> as a Development Platform<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 33
4 Setting Up Your Application<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the design-time artifacts that make up your<br />
application are stored in the repository like files in a file system. You first choose a root folder for your applicationdevelopment<br />
activities, and within this folder you create additional subfolders to organize the applications and the<br />
application content according to your own requirements.<br />
Note: Application development with <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) is<br />
currently only available as an <strong>SAP</strong>-led project solution, for pre-approved customers and partners. This<br />
applies to server-side JavaScript programming, support for ODATA and XMLA, Web server features and<br />
the Web application development environment. For more information, see <strong>SAP</strong> Note 1779803.<br />
As part of the application-development process, you typically need to perform the tasks described in the following<br />
list. Each of the tasks in more detail is described in its own section:<br />
1. Set up delivery units.<br />
To create and manage delivery units, you must set the identity of the vendor with whom the delivery units are<br />
associated. To avoid conflicts with applications from <strong>SAP</strong> or other providers, we recommend that you name<br />
the root application-development folder for your company using the DNS name of your company. For<br />
example, you could use the name acme.com.hr.newHires for the root folder for a new application<br />
managing new hires in a company called acme.<br />
2. Set up <strong>SAP</strong> <strong>HANA</strong> projects.<br />
In <strong>SAP</strong> <strong>HANA</strong>, projects enable you to group together all the artifacts you need for a specific part of the<br />
application-development environment. To start the application-development work flow, you first create a local<br />
workspace in the <strong>SAP</strong> <strong>HANA</strong> Development perspective, which creates a directory structure to store files on<br />
your PC; the workspace you create enables you to synchronize changes in local files with changes in the<br />
repository. Then you can use the <strong>SAP</strong> <strong>HANA</strong> studio to create a project to manage the development activities<br />
for the new application.<br />
3. Maintain repository packages.<br />
To perform the high-level tasks that typically occur during the process of maintaining repository packages,<br />
you need to be familiar with the concepts of packages and package hierarchies, which you use to manage the<br />
artifacts in your applications.<br />
4. Maintain application descriptors.<br />
34<br />
The framework defined by the application descriptors includes the root point in the package hierarchy where<br />
content is to be served to client requests. The framework also defines if the application is permitted to expose<br />
data to client requests, what kind of access to the data is allowed, and what if any privileges are required to<br />
perform actions on packages and package content.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
4.1 Setting up Delivery Units<br />
A delivery unit is a collection of packages that are to be transported together. You assign all the packages<br />
belonging to your application to the same delivery unit to ensure that they are transported consistently together<br />
within your system landscape. Each delivery unit has a unique identity.<br />
The identity of a delivery unit consists of two parts: a vendor name and a delivery-unit name. The combined ID<br />
ensures that delivery units from different vendors are easy to distinguish and follows a pattern that <strong>SAP</strong> uses for<br />
all kinds of software components.<br />
To create and manage delivery units you first need to maintain the identity of the vendor, with whom the delivery<br />
units are associated, and in whose namespace the packages that make up the delivery unit are stored. As part of<br />
the vendor ID maintenance process, you must perform the following tasks:<br />
1. Understand delivery units<br />
You must be familiar with the conventions that exist for delivery-unit names and understand the phases of the<br />
delivery-unit lifecycle.<br />
2. Maintain details of the vendor ID associated with a delivery unit.<br />
Delivery units are located in the namespace associated with the vendor who creates them and who manages<br />
the delivery-unit's lifecycle.<br />
3. Create a delivery unit.<br />
Related Links<br />
Maintaining the Delivery-Unit Vendor ID [page 35]<br />
In <strong>SAP</strong> <strong>HANA</strong>, the vendor ID is used primarily to define the identity of the company developing a software<br />
component that they plan to ship for use with <strong>SAP</strong> <strong>HANA</strong>. If you want to create a delivery unit, it is a<br />
prerequisite to maintain a vendor ID in your system.<br />
Creating a Delivery Unit [page 36]<br />
A delivery unit is a group of transportable objects used for content delivery. You can use a delivery unit to<br />
transport the design-time objects that are stored in the <strong>SAP</strong> <strong>HANA</strong> repository between two systems, for<br />
example, from a development system to a consolidation system.<br />
4.1.1 Maintaining the Delivery-Unit Vendor ID<br />
In <strong>SAP</strong> <strong>HANA</strong>, the vendor ID is used primarily to define the identity of the company developing a software<br />
component that they plan to ship for use with <strong>SAP</strong> <strong>HANA</strong>. If you want to create a delivery unit, it is a prerequisite<br />
to maintain a vendor ID in your system.<br />
Before creating your first own delivery unit you must set the identity of the vendor in the development system's<br />
configuration. To maintain details of the delivery-unit vendor ID, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Switch to the Administration Console perspective.<br />
In the <strong>SAP</strong> <strong>HANA</strong> studio Navigator view choose Administration . Alternatively, use the menu path: Window ><br />
Open Perspective > Administration Console .<br />
3. Display configuration details for the <strong>SAP</strong> <strong>HANA</strong> instance; choose the Configuration tab page.<br />
4. Maintain details of the vendor ID.<br />
In the Configuration tab page, perform the following steps:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 35
a) Locate indexserver.ini in the list of configuration files displayed in the Name column.<br />
b) Expand the indexserver.ini entry.<br />
c) Expand the repository entry.<br />
d) Edit the content_vendor parameter.<br />
e) Double-click content_vendor and enter the name of your vendor. Note that guidelines and conventions<br />
exist for vendor names.<br />
f) Save your changes.<br />
Note: We recommend that you use your DNS name to set the vendor ID, for example, acme.com.<br />
4.1.2 <strong>SAP</strong> <strong>HANA</strong> Delivery Unit Naming Conventions<br />
In <strong>SAP</strong> <strong>HANA</strong>, conventions and guidelines exist for the naming of delivery units (DU). The delivery unit is the<br />
vehicle that lifecycle management (LCM) uses to ship one or more software components from <strong>SAP</strong> (or a partner)<br />
to a customer. The DU is also the container you use to transport application content in your system landscape.<br />
If you are creating a delivery unit, you must adhere to the following naming conventions<br />
● The name of a delivery unit must contain only capital letters (A-Z), digits (0-9), and underscores (_)<br />
● You cannot use an underscore (_) as the first character of a delivery-unit name.<br />
Note: The naming conventions for packages in a delivery unit differ from the naming conventions that<br />
apply to the delivery unit itself. For example, the maximum length of a package name is not restricted to<br />
30 characters; it must be less than 190 characters (including the namespace hierarchy).<br />
4.1.3 Creating a Delivery Unit<br />
A delivery unit is a group of transportable objects used for content delivery. You can use a delivery unit to<br />
transport the design-time objects that are stored in the <strong>SAP</strong> <strong>HANA</strong> repository between two systems, for example,<br />
from a development system to a consolidation system.<br />
In the <strong>SAP</strong> <strong>HANA</strong> studio, you can create a delivery unit in the Quick Launch view of the Modeler perspective :<br />
Note: You cannot create a delivery unit unless you have already defined the delivery unit's vendor ID; the<br />
vendor ID defines the namespace in which the new delivery unit resides.<br />
To create a new delivery unit, perform the following steps:<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, start the Modeler perspective.<br />
2. In the Setup screen area of the Quick Launch tab, choose Delivery Units....<br />
3. Create a new delivery unit.<br />
In the Delivery Units dialog, choose Create...<br />
4. Maintain delivery unit details.<br />
36<br />
a) Enter a name for the new delivery unit.<br />
The delivery unit Name is mandatory.<br />
b) Fill in the other information as required:<br />
Note the following points when entering information:<br />
○ The name of the Vendor is set to the vendor ID that is specified in the system configuration, for<br />
example, acme.com.<br />
○ The Responsible text box enables you to specify the name of the person responsible for managing the<br />
delivery unit.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
Related Links<br />
○ In the text boxes Version, Support Package Version, and Patch Version enter integer values only; the<br />
combined values define the version of the delivery unit that is currently being developed. For<br />
example, enter Version = 1, Support Package Version = 3, and Patch Version = 17 to specify that the<br />
current version of your delivery unit is 1.3.17. The version number is transported to other systems<br />
with every DU transport.<br />
Note: The numbers you enter here refer to the application component that you are<br />
developing; the numbers do not refer to the patch or service-pack level deployed on the <strong>SAP</strong><br />
<strong>HANA</strong> server.<br />
○ The PPMS ID is the product ID used by the <strong>SAP</strong> Product and Production Management System<br />
(PPMS).<br />
Note: Customers and partners should leave the PPMS ID text box empty.<br />
Maintaining the Delivery-Unit Vendor ID [page 35]<br />
In <strong>SAP</strong> <strong>HANA</strong>, the vendor ID is used primarily to define the identity of the company developing a software<br />
component that they plan to ship for use with <strong>SAP</strong> <strong>HANA</strong>. If you want to create a delivery unit, it is a<br />
prerequisite to maintain a vendor ID in your system.<br />
<strong>SAP</strong> <strong>HANA</strong> Delivery Unit Naming Conventions [page 36]<br />
In <strong>SAP</strong> <strong>HANA</strong>, conventions and guidelines exist for the naming of delivery units (DU). The delivery unit is the<br />
vehicle that lifecycle management (LCM) uses to ship one or more software components from <strong>SAP</strong> (or a<br />
partner) to a customer. The DU is also the container you use to transport application content in your system<br />
landscape.<br />
4.2 Using <strong>SAP</strong> <strong>HANA</strong> Projects<br />
Projects group together all the artifacts you need for a specific part of the application-development environment.<br />
Before you can start the application-development workflow, you must create a project, which you use to group<br />
together all your application-related artifacts. However, before you create a project, you must create a repository<br />
workspace, which enables you to synchronize changes in local files with changes in the repository. As part of the<br />
project-creation process, you perform the following tasks:<br />
1. Create a development workspace.<br />
The workspace is the link between the <strong>SAP</strong> <strong>HANA</strong> repository and your local filesystem, where you work on<br />
project-related objects.<br />
2. Create a project.<br />
Create a new project for a particular application or package; you can use the project to collect in a convenient<br />
place all your application-related artifacts.<br />
3. Share a project.<br />
Sharing a project enables you to ensure that changes you make to project-related files are visible to other<br />
team members and applications. Shared projects are available for import by other members of the<br />
application-development team.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 37
4. Import a project.<br />
Import a project (and its associated artifacts) that has been shared by another member of the applicationdevelopment<br />
team.<br />
Related Links<br />
Create a Development Workspace [page 39]<br />
A workspace is a local directory that you map to all (or part) of a package hierarchy in the <strong>SAP</strong> <strong>HANA</strong><br />
repository. When you check out a package from the repository, <strong>SAP</strong> <strong>HANA</strong> copies the contents of the package<br />
hierarchy to your workspace, where you can work on the files..<br />
Create a New Project [page 40]<br />
Before you can start the application-development workflow, you must create a project, which you use to group<br />
all your application-related artifacts.<br />
Share a Project [page 40]<br />
Before you can start working on files associated with a new project, you must share the project; sharing a<br />
project enables you to track and synchronize local changes with the repository.<br />
Import a Project [page 41]<br />
Before you can start the application-development workflow, you must either create a new project and share it<br />
(with the repository), or import a shared project from the repository into your workspace. Importing a project<br />
enables you to track and synchronize local changes with the colleagues working on the objects in the imported<br />
project.<br />
4.2.1 <strong>SAP</strong> <strong>HANA</strong> Repository: Workspaces<br />
The place where you work on project-related objects is called a repository workspace. A workspace is an<br />
environment that maps a local directory to all (or part) of a package hierarchy in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
In <strong>SAP</strong> <strong>HANA</strong> studio, the repository tools enable you to view and browse the entire hierarchy of design-time<br />
objects stored in the repository. However, when you checkout a package from the repository, <strong>SAP</strong> <strong>HANA</strong> copies<br />
the contents of the package hierarchy to your workspace, where you can work on the files in your local file system.<br />
Note: Before you can create a workspace you must maintain connection information in the <strong>SAP</strong> <strong>HANA</strong><br />
database user store.<br />
To start development work with <strong>SAP</strong> <strong>HANA</strong> studio, for example, to checkout the contents of a package, you must<br />
create a repository workspace. The workspace contains a system folder with metadata and package folders for<br />
the repository content. The file-system folders and their subfolders reflect the package hierarchy in the<br />
repository; the repository client ensures that changes are synchronized. You can use <strong>SAP</strong> <strong>HANA</strong> studio to<br />
perform the following workspace-related actions in the repository:<br />
● Checkout folders and files from the repository<br />
● Commit changes to the repository<br />
● Activate the committed changes<br />
● Revert inactive changes to the previously saved version<br />
The commit operation detects all changes in packages that you configure <strong>SAP</strong> <strong>HANA</strong> studio tool to track and<br />
writes the detected changes back to the repository. The repository client tools also support synchronization with<br />
changes on the server, including conflict detection and merging of change. All workspace-related repository<br />
actions are available as context-sensitive menu options in <strong>SAP</strong> <strong>HANA</strong> studio. For example, if you right click a<br />
repository object at the top of the package hierarchy in the Project Explorer in <strong>SAP</strong> <strong>HANA</strong> studio, you can commit<br />
and activate all changed objects within the selected hierarchy.<br />
38<br />
Note: If you create a new project using <strong>SAP</strong> <strong>HANA</strong> studio, you can assign the new project to an existing<br />
workspace.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
4.2.2 Creating a Repository Workspace<br />
A workspace is a local directory that you map to all (or part) of a package hierarchy in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
When you check out a package from the repository, <strong>SAP</strong> <strong>HANA</strong> copies the contents of the package hierarchy to<br />
your workspace, where you can work on the files..<br />
Before you can start work on the development of the application, you need to set up a workspace, where you store<br />
checked-out copies of your application’s source-code files.<br />
To create a new workspace in the <strong>SAP</strong> <strong>HANA</strong> studio, perform the following steps:<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Choose the <strong>SAP</strong> <strong>HANA</strong> Repositories view.<br />
4. Choose Create Workspace…<br />
The Create Workspace… button is located in the top right-hand corner of the <strong>SAP</strong> <strong>HANA</strong> Repositories view.<br />
5. Specify the workspace details. In the Create New Repository Workspace dialog, enter the following<br />
information and choose Finish:<br />
a) Specify the <strong>SAP</strong> <strong>HANA</strong> system, for which you want to create a new workspace.<br />
b) Enter a workspace name, for example the name of the <strong>SAP</strong> <strong>HANA</strong> system where the repository is located.<br />
To avoid the potential for confusion, it is recommended to associate one workspace with one repository.<br />
c) Specify where the workspace root directory should be located on your local file system, for example: C:<br />
\users\username\workspaces<br />
The new workspace is displayed in the <strong>SAP</strong> <strong>HANA</strong> Repositories view.<br />
Note: Although the packages and objects in the chosen repository are visible in the <strong>SAP</strong> <strong>HANA</strong><br />
Repositories view, you cannot open or work on the objects here. To work on objects, you must create<br />
a project and use the Project Explorer view.<br />
4.2.3 <strong>SAP</strong> <strong>HANA</strong> Studio Projects<br />
Before you can start the application-development workflow, you must create a project, which you use to group all<br />
your application-related artifacts.<br />
Projects group together all the artifacts you need for a specific part of the application-development environment.<br />
A basic project contains folders and files. More advanced projects are used for builds, version management,<br />
sharing, and the organization and maintenance of resources.<br />
Projects enable multiple people to work on the same files at the same time. By committing project-related files to<br />
the repository and activating them, you enable team members to see the latest changes.<br />
You can share and unshare projects. Sharing a project associates it with a particular package in the repository<br />
linked to a particular workspace. The act of sharing the project sets up a link between the workspace and the<br />
repository and enables you to track and synchronize local changes with the versions of the objects stored in the<br />
repository. When a project is shared, it becomes available to other people with authorization to access to the<br />
repository, for example, colleagues in an application-development team. Team members can import a shared<br />
project and see and work on the same files as the creator of the project.<br />
Note: Always unshare a project before deleting it.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 39
In the <strong>SAP</strong> <strong>HANA</strong> studio you can create a project at any package level, which enables a fine level of control of the<br />
artifacts that may (or may not) be exposed by sharing the project.<br />
4.2.4 Creating a Project for <strong>SAP</strong> <strong>HANA</strong> XS<br />
Before you can start the application-development workflow, you must create a project, which you use to group all<br />
your application-related artifacts.<br />
Projects group together all the artifacts you need for a specific part of your application-development environment.<br />
Depending on the type of project you are working on, the project can include build tools, too. A basic project<br />
contains folders and files. More advanced projects are used for builds, version management, sharing, and the<br />
organization and maintenance of resources.<br />
To create a new project in the <strong>SAP</strong> <strong>HANA</strong> studio, perform the following steps:<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Choose the Project Explorer view.<br />
4. Right-click the white space in the Project Explorer view and choose New > Project… in the popup menu.<br />
The type of project you create determines the details you have to provide in the New Project dialog that<br />
appears.<br />
a) Enter a project name that describes what the project is about, for example: XS_JavaScript, XS_OData<br />
or XS_<strong>SAP</strong>UI5.<br />
b) Click Finish to create the new project.<br />
The new project is displayed in the Project Explorer view.<br />
Note: The contents of the project depend on the type of project you create. For example, a general<br />
project is empty immediately after creation; a JavaScript project contains all the resource files<br />
associated with a JavaScript project, such as libraries and build-environment artifacts.<br />
4.2.5 Sharing a Project for <strong>SAP</strong> <strong>HANA</strong> XS<br />
Before you can start working on files associated with a new project, you must share the project; sharing a project<br />
enables you to track and synchronize local changes with the repository.<br />
When you share a project, you set up a connection to the <strong>SAP</strong> <strong>HANA</strong> repository associated with a particular <strong>SAP</strong><br />
<strong>HANA</strong> instance. Sharing the project enables you to ensure that changes you make to project-related files are<br />
visible to other team members and applications. Other developers can import a shared project and work on the<br />
same files.<br />
Note: Use the Project Explorer view in the <strong>SAP</strong> <strong>HANA</strong> studio to check if a project is shared. In addition to<br />
the project name, a shared project displays the <strong>SAP</strong> <strong>HANA</strong> system ID of the repository where the shared<br />
artifacts are located, a <strong>SAP</strong> <strong>HANA</strong> user name, and the path to the repository package to which the shared<br />
project is assigned, for example. "XSJS_myproject [SID (dbusername,<br />
'sap.hana.xs.app1')].<br />
To share a project in the <strong>SAP</strong> <strong>HANA</strong> studio, perform the following steps:<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
40<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
3. Open the Project Explorer view.<br />
4. Share the project<br />
Right-click the project you want to share and choose Team > Share Project… in the pop-up menu.<br />
5. Select the repository type.<br />
The Share Project dialog displays a list of all available repository types; choose <strong>SAP</strong> <strong>HANA</strong> Repository and<br />
choose Next.<br />
6. Select the repository workspace where the project should be located.<br />
7. Specify the package that you want to associate the shared project with.<br />
The Share Project dialog displays the suggested location for the shared project in the New Project location<br />
screen area. The default location is the name of the workspace with the name of the project you want to<br />
share. Choose Browse... to locate the package you want to associate the shared project with. The selected<br />
package is displayed in the Path to package text box.<br />
Note: The Keep project folder option appends the name of the project you are sharing to the name of<br />
the workspace in which you are sharing the project and creates a new package with the name of the<br />
shared project under the workspace location displayed. Use this option only if you want to create<br />
multiple projects for a selected package, for example, if you are creating a root project in your root<br />
application package.<br />
8. Click Finish to complete the project-sharing procedure.<br />
9. Add new files as required<br />
At this point you can start adding project-specific files to the shared project. These artifacts can then be<br />
committed to the repository, where they reside as inactive objects until they are activated, for example, using<br />
the Team Activate option in the context-sensitive menus available in the Project Navigator view.<br />
Note: The Project Explorer view decorates the file icons to indicate the current state of the repository<br />
files, for example: local (not yet committed), committed (inactive), and active (available for use by<br />
others).<br />
10. Make the project available for import, for example, so that others can join it and make changes to project<br />
content.<br />
The project-sharing procedure creates some artifacts (for example, the .project file) that must be<br />
committed to the repository and activated so that other team members can import the project more easily<br />
into their workspace. The .project file is used in several dialogs to populate the list of available projects.<br />
Related Links<br />
Note: Use the <strong>SAP</strong> <strong>HANA</strong> Repositories view to import projects (and checkout project content).<br />
Importing a Project in <strong>SAP</strong> <strong>HANA</strong> XS [page 41]<br />
Before you can start the application-development workflow, you must either create a new project and share it<br />
(with the repository), or import a shared project from the repository into your workspace. Importing a project<br />
enables you to track and synchronize local changes with the colleagues working on the objects in the imported<br />
project.<br />
4.2.6 Importing a Project in <strong>SAP</strong> <strong>HANA</strong> XS<br />
Before you can start the application-development workflow, you must either create a new project and share it<br />
(with the repository), or import a shared project from the repository into your workspace. Importing a project<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 41
enables you to track and synchronize local changes with the colleagues working on the objects in the imported<br />
project.<br />
To import an existing project from the repository into your workspace, perform the following steps.<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Choose the <strong>HANA</strong> Repositories view.<br />
4. Right-click the package where the project you want to import is located and choose Checkout and Import<br />
Projects... in the popup menu.<br />
Projects can be assigned to a package at any level of the package hierarchy. If you know where the project is<br />
located, browse to the package first before choosing the Checkout and Import Projects... option. This reduces<br />
the amount of files to checkout and download to your local file system.<br />
Note: The existence of a .project file in a package identifies the package as being associated with a<br />
project.<br />
The <strong>SAP</strong> <strong>HANA</strong> studio checks out the content of the selected package and displays any projects it finds in the<br />
Projects screen area.<br />
5. Select the projects to import.<br />
If multiple projects are available for import, select the projects you want to import.<br />
6. Choose Finish to import the selected projects.<br />
You can add the imported project to your Working Sets.<br />
Note: A working set is a concept similar to favorites in a Web browser, which contain the objects you<br />
work on most frequently.<br />
4.3 Maintaining Repository Packages<br />
All content delivered as part of the application you develop for <strong>SAP</strong> <strong>HANA</strong> is stored in packages in the <strong>SAP</strong> <strong>HANA</strong><br />
repository. The packages are arranged in a hierarchy that you define to help make the process of maintaining the<br />
packages transparent and logical.<br />
To perform the high-level tasks that typically occur during the process of maintaining repository packages, you<br />
need to be familiar with the concepts of packages and package hierarchy that create and maintain the artifacts for<br />
your applications. You also need to know about the privileges the application developers will need to have access<br />
to (and perform operations on) the packages.<br />
Note: You can also create and delete packages in the Project Explorer, for example, by creating or deleting<br />
folders in shared projects and committing and activating these changes. However, to maintain advanced<br />
package properties (for example, privileges, component, the package maintainer, and so on) you must<br />
use the Modeling perspective in the <strong>SAP</strong> <strong>HANA</strong> studio..<br />
As part of the process of maintaining your application packages, you typically perform the following tasks:<br />
42<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
1. Create a package<br />
Packages are necessary to group logically distinct artifacts together in one object location that is easy to<br />
transport.<br />
2. Define the package hierarchy<br />
The package hierarchy is essential for ease of maintenance as well as the configuration of access to packages<br />
and the privileges that are required to perform actions on the packages.<br />
3. Define package privileges<br />
You can set package authorizations for a specific user or for a role. Authorizations that are assigned to a<br />
repository package are implicitly assigned to all sub-packages, too.<br />
Related Links<br />
Creating a package [page 46]<br />
In <strong>SAP</strong> <strong>HANA</strong>, a package contains a selection of repository objects. You assemble a collection of packages into<br />
a delivery unit, which you can use to transport the repository objects between <strong>SAP</strong> <strong>HANA</strong> systems.<br />
Defining the package hierarchy [page 47]<br />
Packages belonging to an application-development delivery unit (DU) should be organized in a clear<br />
hierarchical structure under a single root package representing the vendor, for example, acme.<br />
Defining package privileges [page 46]<br />
In the <strong>SAP</strong> <strong>HANA</strong> repository, you can set package authorizations for a specific user or for a role.<br />
Authorizations that are assigned to a repository package are implicitly assigned to all sub-packages, too. You<br />
can also specify if the assigned user authorizations can be passed on to other users.<br />
4.3.1 <strong>SAP</strong> <strong>HANA</strong> Repository Packages and Namespaces<br />
In <strong>SAP</strong> <strong>HANA</strong>, a package typically consists of a collection of repository objects, which can be transported between<br />
systems. Multiple packages can be combined in a delivery unit (DU).<br />
A <strong>SAP</strong> <strong>HANA</strong> package specifies a namespace in which the repository objects exist. Every repository object is<br />
assigned to a package, and each package must be assigned to a specific delivery unit. In the repository, each<br />
object is uniquely identified by a combination of the following information:<br />
● Package name<br />
● Object name<br />
● Object type<br />
Note: Multiple objects of the same type can have the same object name if they belong to different<br />
packages.<br />
Before you start the package development process, consider the following important points:<br />
● Package hierarchy<br />
Each vendor uses a dedicated namespace, and the package hierarchy you create enables you to store the<br />
various elements of an application in a logical order that is easy to navigate.<br />
● Package type<br />
Packages can be structural or non-structural; some packages contain content; other packages contain only<br />
other (sub)packages.<br />
● Package naming conventions<br />
There are recommendations and restrictions regarding package names, for example, the name's maximum<br />
length and what if any characters must not be used.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 43
Package Hierarchy<br />
You can create a package hierarchy, for example, by establishing a parent-child type relationship between<br />
packages. The assignment of packages to delivery units is independent of the package hierarchy; packages in a<br />
parent-child relationship can belong to different delivery units. <strong>SAP</strong> recommends that you assign to one specific<br />
delivery unit all packages that are part of a particular project or project area.<br />
The package hierarchy for a new project typically includes sub-packages, for example, to isolate the data model<br />
from the business logic. Although there are no package interfaces to enforce visibility of objects across packages,<br />
this separation of logical layers of development is still a recommended best practice.<br />
Note: You can only assign one project per package; this is important to remember if you have a mixture of<br />
design-time objects that need to be used in multiple projects, for example: server-side JavaScript (XSJS),<br />
<strong>SAP</strong>UI5, and a general project (for procedures).<br />
The following simple example shows a package structure containing tutorials for the use of a new application:<br />
sap<br />
\<br />
hana<br />
\<br />
app1<br />
\<br />
code<br />
demos<br />
docs<br />
\<br />
tutorials<br />
manuals<br />
help<br />
All content delivered by <strong>SAP</strong> should be in a sub-package of "sap". Partners and customers should choose their<br />
own root package to reflect their own name (for example, the domain name associated with the company) and<br />
must not create packages or objects under the "sap" root structural package. This rules ensures that customer or<br />
partner created content will not be overwritten by an <strong>SAP</strong> update or patch.<br />
Note: <strong>SAP</strong> reserves the right to deliver without notification changes in packages and models below the<br />
"sap" root structural package.<br />
There are no system mechanisms for enforcing the package hierarchy. The "sap" root structural package is not<br />
automatically protected. However, by default you cannot change the content of packages that did not originate in<br />
the system. In addition, an authorization concept exists, which enables you to control who can change what inside<br />
packages.<br />
Package Types<br />
<strong>SAP</strong> <strong>HANA</strong> Application Services provide or allow the following package types:<br />
● Structural<br />
44<br />
Package only contains sub-packages; it cannot contain repository objects.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
● Non-Structural<br />
Package contains both repository objects and subpackages.<br />
The following packages are delivered by default with the repository:<br />
● sap<br />
Transportable package reserved for content delivered by <strong>SAP</strong>. Partners and customers must not use the sap<br />
package; they must create and use their own root package to avoid conflicts with software delivered by <strong>SAP</strong>,<br />
for example when <strong>SAP</strong> updates or overwrites the sap package structure during an update or patch process.<br />
● system-local<br />
Non-transportable, structural packages (and subpackages). Content in this package (and any subpackages)<br />
is considered system local and cannot be transported. This is similar to the concept of the $tmp development<br />
class in <strong>SAP</strong> NetWeaver ABAP.<br />
● system-local.generated<br />
Transportable, structural packages for generated content, that is; content not created by manual user<br />
interaction<br />
● system-local.private<br />
Transportable, structural sub-packages containing objects that belong to individual users and are named<br />
after these users (and are exclusively reserved for these users). For example, system-<br />
local.private.<br />
Package Naming Conventions<br />
The following rules apply to package names:<br />
● Permitted characters<br />
Lower/upper case letters (aA-zZ), digits (0-9), hyphens (-), and dots (.) are permitted in package names.<br />
Dots in a package name define a logical hierarchy. For example, "a.b.c" specifies a package "a" that contains<br />
sub-package "b", which in turn contains sub-package "c".<br />
● Forbidden characters<br />
A package name must not start with either a dot (.) or a hyphen (-) and cannot contain two or more<br />
consecutive dots (..).<br />
● Package name length<br />
The maximum permitted length of a package name is 190 characters. To avoid problems, we recommend you<br />
restrict the length of package names to well under the 190-character limit.<br />
● Package namespace length<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 45
The name of the complete package namespace hierarchy (for example, "aa.bb.cc.zz" including dots) must not<br />
be more than 190 characters long. To avoid problems, we recommend you restrict the length of the package<br />
namespace to well under the 190-character limit.<br />
4.3.2 Defining Repository Package Privileges<br />
In the <strong>SAP</strong> <strong>HANA</strong> repository, you can set package authorizations for a specific user or for a role. Authorizations<br />
that are assigned to a repository package are implicitly assigned to all sub-packages, too. You can also specify if<br />
the assigned user authorizations can be passed on to other users.<br />
To set user (or role) authorizations for repository packages, perform the following steps:<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, open the Navigator view of the Modeler perspective.<br />
2. In the Navigator view, expand the Security Roles/Users node for the system hosting the repository that<br />
contains the packages you want to grant access to.<br />
You can also define roles via source files; roles defined in this way can be assigned to a delivery unit and<br />
transported to other systems.<br />
3. Double click the user (or role) to whom you want to assign authorizations.<br />
4. Open the Package Privileges tab page.<br />
5. Choose [+] to add one or more packages. Press and hold the Ctrl key to select multiple packages.<br />
6. In the Select Repository Package dialog, use all or part of the package name to locate the repository package<br />
that you want to authorize access to.<br />
7. Select one or more repository packages that you want to authorize access to; the selected packages appear<br />
in the Package Privileges tab page.<br />
8. Select the packages to which you want authorize access and, in the Privileges for screen page, check the<br />
required privileges, for example:<br />
a) REPO.READ<br />
Read access to the selected package and design-time objects (both native and imported)<br />
b) REPO.EDIT_NATIVE_OBJECTS<br />
Authorization to modify design-time objects in packages originating in the system the user is working in<br />
c) REPO.ACTIVATE_NATIVE_OBJECTS<br />
Authorization to activate/reactivate design-time objects in packages originating in the system the user is<br />
working in<br />
d) REPO.MAINTAIN_NATIVE_PACKAGES<br />
Authorization to update or delete native packages, or create sub-packages of packages originating in the<br />
system in which the user is working<br />
4.3.3 Creating a Package<br />
In <strong>SAP</strong> <strong>HANA</strong>, a package contains a selection of repository objects. You assemble a collection of packages into a<br />
delivery unit, which you can use to transport the repository objects between <strong>SAP</strong> <strong>HANA</strong> systems.<br />
You can use packages to manage the various elements of your application development project. To create a<br />
project, perform the following steps:<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, start the Modeler perspective.<br />
2. In the New screen area of the Quick Launch tab page, choose Package and choose Create....<br />
3. Maintain the package details.<br />
46<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
In the New Package dialog, enter information in the following fields:<br />
a) Enter a name for the new package.<br />
The package Name is mandatory.<br />
b) Fill in the other optional information as required:<br />
Related Links<br />
Use the Delivery Unit drop-down list to assign the new package to a delivery unit.<br />
Choose Translation if you intend to have the package content localized. You must maintain the translation<br />
details.<br />
<strong>SAP</strong> <strong>HANA</strong> Delivery-Unit Translation Details [page 353]<br />
The <strong>SAP</strong> <strong>HANA</strong> repository includes features for translating package-related metadata texts. If you plan to<br />
translate the contents of the new delivery unit you create, you must maintain translation details.<br />
4.3.4 Defining a Package Hierarchy<br />
Packages belonging to an application-development delivery unit (DU) should be organized in a clear hierarchical<br />
structure under a single root package representing the vendor, for example, acme.<br />
The package hierarchy for a new project might include sub-packages, for example, to isolate the data model from<br />
the business logic. Although there are no package interfaces to enforce visibility of objects across packages, this<br />
separation of logical layers of development is still a recommended best practice.<br />
Note: You can only assign one project per package; this is important to remember if you have a mixture of<br />
design-time objects that need to be used in multiple projects, for example: server-side JavaScript (XSJS),<br />
<strong>SAP</strong>UI5, and a general project (for procedures).<br />
The following simple example shows a package structure containing tutorials for the use of a new application:<br />
acme<br />
\<br />
hana<br />
\<br />
app1<br />
\<br />
docs<br />
\<br />
tutorials<br />
● Package hierarchy<br />
Each vendor uses a dedicated namespace, for example, acme.<br />
● Package type<br />
Note: Do not use the namespace sap to build your application hierarchy. The namespace sap is<br />
reserved for use by <strong>SAP</strong>; packages created in the sap namespace are overwritten by system updates.<br />
Some packages contain content; other packages contain only other (sub)packages. Packages can also<br />
contain both objects and (sub)packages.<br />
● Package naming conventions<br />
There are recommendations and restrictions regarding package names.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 47
To set up a package hierarchy in the <strong>SAP</strong> <strong>HANA</strong> repository, perform the following steps:<br />
1. Create a new root package.<br />
Open the Modeler perspective and perform the following steps:<br />
a) Choose New > Package .<br />
b) Choose Create...<br />
2. Maintain the package details.<br />
In the Create Package dialog, perform the following steps:<br />
a) Enter the name of the package (mandatory).<br />
<strong>Guide</strong>lines and conventions apply to package names.<br />
b) Enter a package description (optional).<br />
c) Specify the delivery unit that the package is assigned to.<br />
You can add additional packages to a delivery unit at a later point in time, too.<br />
d) Specify a language for the package content.<br />
e) Assign responsibility of the package to a specific user (optional).<br />
By default, the responsible user for a new package is the database user connected to the <strong>SAP</strong> <strong>HANA</strong><br />
repository in the current <strong>SAP</strong> <strong>HANA</strong> studio session.<br />
f) Maintain translation details.<br />
If you plan to have the content translated, you need to maintain the translation details; this is covered in<br />
another topic.<br />
3. Create a new subpackage.<br />
In the Navigator view of the Modeler perspective, perform the following steps:<br />
a) Right-click the package to which you want to add a new subpackage.<br />
b) In the pop-up menu, choose New > Package...<br />
4. Maintain the subpackage details.<br />
In the Create Package dialog, perform the following steps:<br />
a) Enter the name of the subpackage (mandatory).<br />
<strong>Guide</strong>lines and conventions apply to package names.<br />
b) Enter a description for the new subpackage (optional).<br />
c) Specify the delivery unit that the subpackage is assigned to.<br />
You can add additional packages to a delivery unit at a later point in time, too.<br />
d) Specify a language for the subpackage content.<br />
e) Assign responsibility of the subpackage to a specific user (optional).<br />
By default, the responsible user for a new package is the database user connected to the <strong>SAP</strong> <strong>HANA</strong><br />
repository in the current <strong>SAP</strong> <strong>HANA</strong> studio session.<br />
f) Maintain translation details.<br />
Related Links<br />
If you plan to have the content translated, you need to maintain the translation details; this is covered in<br />
another topic.<br />
<strong>SAP</strong> <strong>HANA</strong> Delivery Unit Naming Conventions [page 36]<br />
In <strong>SAP</strong> <strong>HANA</strong>, conventions and guidelines exist for the naming of delivery units (DU). The delivery unit is the<br />
vehicle that lifecycle management (LCM) uses to ship one or more software components from <strong>SAP</strong> (or a<br />
partner) to a customer. The DU is also the container you use to transport application content in your system<br />
landscape.<br />
48<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
Maintaining Translation Details [page 353]<br />
Translation details provide a brief overview of the type and current status of the text objects to be translated,<br />
for example, by specifying the technical area of the new delivery unit and indicating the current status of<br />
translation texts.<br />
4.4 Creating the Application Descriptors<br />
When you develop and deploy applications in the context of <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong><br />
<strong>HANA</strong> XS), you must define the application descriptors, which describe the framework in which the application<br />
runs. The framework defined by the application descriptors includes the root point in the package hierarchy where<br />
content is to be served to client requests, whether the application is permitted to expose data to client requests,<br />
what kind of access to the data is allowed, and what if any privileges are required to perform actions on packages<br />
and package content.<br />
To perform the high-level tasks that make up the process of defining the application descriptors, you must be<br />
familiar with the concept of the application descriptor, the application-access file, and if required, the application-<br />
privileges file. Maintaining the application descriptors involves the following tasks:<br />
1. Creating the application descriptor file.<br />
The package that contains the application descriptor file becomes the root path of the resources exposed to<br />
client requests by the application you develop.<br />
2. Creating the application-access file.<br />
The application-access file enables you to specify who or what is authorized to access the content exposed by<br />
the application package and what content they are allowed to see.<br />
3. Creating the application-privileges file. (Optional)<br />
The application-privileges file can be used to define the authorization privileges required for access to an<br />
application, for example, to start the application or to perform administrative actions on an application.<br />
Related Links<br />
Create an application descriptor [page 50]<br />
Each application that you want to develop and deploy on <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong><br />
<strong>HANA</strong> XS) must have an application-descriptor file. The application descriptor is the core file that you use to<br />
describe an application's framework within <strong>SAP</strong> <strong>HANA</strong> XS.<br />
Create an application-access file [page 57]<br />
The application-access file enables you to specify who or what is authorized to access the content exposed by<br />
the application package and what content they are allowed to see.<br />
Create an application-privileges file [page 60]<br />
The application-privileges (.xssprivileges) file can be used to grant authorization levels for an application,<br />
for example, to start the application or perform administrative actions on an application.<br />
4.4.1 The <strong>SAP</strong> <strong>HANA</strong> XS Application Descriptor<br />
Each application that you want to develop and deploy on <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong><br />
XS) must have an application descriptor file. The application descriptor is the core file that you use to describe an<br />
application's framework within <strong>SAP</strong> <strong>HANA</strong> XS.<br />
The package that contains the application descriptor file becomes the root path of the resources exposed to client<br />
requests by the application you develop.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 49
Note: The application-descriptor file has no contents and no name; it only has the file extension “xsapp”,<br />
for example, .xsapp. For backward compatibility, content is allowed in the .xsapp file but ignored.<br />
The application descriptor file performs the following operations:<br />
● Determines the called application<br />
The application root is determined by the package containing the .xsapp file. If the package sap.test<br />
contains the file .xsapp, the application will be available under the URL http://:/<br />
sap.test/.<br />
4.4.2 Create an Application Descriptor File<br />
Each application that you want to develop and deploy on <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong><br />
XS) must have an application-descriptor file. The application descriptor is the core file that you use to describe an<br />
application's framework within <strong>SAP</strong> <strong>HANA</strong> XS.<br />
The package that contains the application-descriptor file becomes the root path of the resources exposed by the<br />
application you develop.<br />
1. Create a root package for your application, for example, helloxsjs.<br />
2. Create an application descriptor for your application and place it in the root package you created in the<br />
previous step.<br />
The application descriptor is the core file that you use to describe an application's availability within <strong>SAP</strong><br />
<strong>HANA</strong> Extended Application Services. The application-descriptor file has no contents and no name; it only has<br />
the file extension .xsapp..<br />
Note: For backward compatibility, content is allowed in the .xsapp file but ignored.<br />
3. Save and activate your changes and additions.<br />
4.4.3 The Application-Access File<br />
<strong>SAP</strong> <strong>HANA</strong> XS enables you to define access to each individual application package that you want to develop and<br />
deploy.<br />
The application-access file enables you to specify who or what is authorized to access the content exposed by a<br />
<strong>SAP</strong> <strong>HANA</strong> XS application package and what content they are allowed to see. For example, you use the<br />
application-access file to specify if authentication is to be used to check access to package content and whether if<br />
rules are in place for the exposure of target and source URLs.<br />
The application-access file does not have a name; it only has the file extension .xsaccess. The content of<br />
the .xsaccess file is formatted according to JSON rules and is associated with the package it belongs to as well<br />
as any subpackages lower in the package hierarchy. Multiple .xsaccess files are allowed, but only at different<br />
levels in the package hierarchy. This enables you to specify different application-access rules for individual<br />
packages and subpackages in the package hierarchy.<br />
Note: You cannot place two .xsaccess files in the same package. Furthermore, the rules specified in<br />
a .xsaccess file that is associated with a subpackage take precedence over any rules specified in<br />
a .xsaccess file associated with any parent package higher up the package hierarchy.<br />
The application-access file performs the following operations:<br />
● Data exposure<br />
50<br />
Use the exposed keyword to specify if package content is to be exposed to client requests via HTTP.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
Note: Exposed package content can include design-time objects, for example, tables and views.<br />
● Authentication rules<br />
Use the authentication keyword to enable authorization for the requests in URLs either at the application level<br />
or for single packages in an application. The following authentication methods are supported:<br />
○ <strong>SAP</strong> logon tickets<br />
<strong>SAP</strong> logon tickets enable single sign-on across <strong>SAP</strong> boundaries; <strong>SAP</strong> logon tickets can also be used as<br />
authentication for access to third-party applications.<br />
○ Form-based authentication<br />
Redirect the logon request to a form to fill in, for example, on a Web page.<br />
○ Basic (user name and password)<br />
Log on with a recognized user name and password<br />
The authentication methods can also be written as an array, for example, to allow applications to support<br />
multiple authentication methods. The order of the authentication methods in the array should proceed from<br />
strongest to weakest, for example:<br />
1. <strong>SAP</strong> logon ticket<br />
2. Form-based<br />
3. Basic authentication<br />
● Application authorization<br />
Use the authorization keyword in the .xsaccess file to specify which authorization level is required by a user<br />
for access to a particular application package. The authorization levels you can choose from are defined in<br />
the .xsprivileges file, for example, "execute" for basic privileges, or "admin" for administrative privileges<br />
on the specified package.<br />
● URL rewrite rules<br />
Use the rewrite_rules keyword in the .xsaccess file to hide internal URL path details from external users,<br />
clients, and search engines. It is not possible to define global rewrite rules; the rules you define apply to the<br />
specified local application only. Rules are specified as a source-target pair where the source is written in the<br />
JavaScript regex syntax, and the target is a simple string where references to the groups found can be<br />
inserted using $groupnumber.<br />
● Connection security<br />
Use the force_ssl keyword in the .xsaccess file to enforce the use of secure HTTP (SSL/HTTPS) for client<br />
connections. Browser requests that do not use SSL/HTTPS are refused and the 403 Forbidden page is<br />
displayed. Note that if you set the force_ssl option, then you must ensure that the <strong>SAP</strong> Web Dispatcher is<br />
configured to accept and manage HTTPS requests. For more information about configuring the <strong>SAP</strong> Web<br />
Dispatcher to use HTTPS/SSL see the <strong>SAP</strong> <strong>HANA</strong> Administration <strong>Guide</strong>.<br />
Note:<br />
● Entity Tags<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
If the <strong>SAP</strong> Webdispatcher sends the header “x-sap-webdisp-ap” with the HTTPS port, the request is<br />
redirected to a HTTPS page, for example: http://..:80/test -> https://..:433/test.<br />
Otherwise, a 403 error is displayed.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 51
You can allow or prevent the generation of entity tags (etags) for static Web content using the enable_etags<br />
keyword in the .xsaccess file. Etags are used to improve caching performance, for example, so that the<br />
same data is not resent if no change has occurred since the last request.<br />
● MIME Mapping<br />
MIME means Multipurpose Internet Mail Extensions. You can use the mime_mapping keyword in<br />
the .xsaccess file to define the way in which to map certain file suffixes to required MIME types:<br />
"mime_mapping": [ {"extension":"jpg", "mimetype":"image/jpeg"} ]<br />
The Application-Access (.xsaccess) File<br />
The following example, shows the composition and structure of the <strong>SAP</strong> <strong>HANA</strong> XS application access<br />
(.xsaccess) file. In this file, data is available to client requests. The authentication methods specified are<br />
<strong>SAP</strong> logon ticket and then, as a fall-back option if the logon with the <strong>SAP</strong> logon ticket fails, a logon with a<br />
user name and password. Allowing a fall-back log-on mechanism is useful if the requesting client has<br />
problems handling the <strong>SAP</strong> logon ticket mechanism.<br />
{<br />
$3"<br />
}<br />
Related Links<br />
"exposed" : true, // Expose data via http<br />
"authentication" : // Authentication method<br />
[<br />
{<br />
"method": "LogonTicket",<br />
},<br />
{<br />
"method" : "Basic"<br />
},<br />
],<br />
"authorization": // Grant package privileges<br />
[<br />
"sap.xse.test::Execute",<br />
"sap.xse.test::Admin"<br />
]<br />
"rewrite_rules" : // URL rewriting rules<br />
[<br />
{<br />
"source": "/entries/(\\d+)/(\\d+)/(\\d+)/",<br />
"target": "/logic/entries.xsjs?year=$1&month=$2&day=<br />
}<br />
],<br />
"mime_mapping" : // Map file-suffix to MIME type<br />
[<br />
{<br />
"extension":"jpg", "mimetype":"image/jpeg"<br />
}<br />
],<br />
"force_ssl" : true, // Refuse request if not SSL<br />
"enable_etags":false // Prevent etag generation<br />
http://help.sap.com/hana/hana_admin_en.pdf<br />
52<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
Application-Access File Keyword Options [page 53]<br />
The application-access (.xsaccess) file enables you to specify whether or not to expose package content,<br />
which authentication method is used to grant access, and what content is visible.<br />
4.4.4 Application-Access File Keyword Options<br />
The application-access (.xsaccess) file enables you to specify whether or not to expose package content, which<br />
authentication method is used to grant access, and what content is visible.<br />
The Application Access (.xsaccess) File<br />
The following example shows all possible keyword combinations in the <strong>SAP</strong> <strong>HANA</strong> XS application-access<br />
(.xsaccess) file.<br />
}<br />
{<br />
exposed<br />
{<br />
Note: In the form shown below, the .xsaccess file is not a working model; it is used to illustrate all<br />
possible options.<br />
"exposed" : true,<br />
"authentication" : // null = no auth required,<br />
[<br />
{<br />
"method": "LogonTicket",<br />
},<br />
{<br />
"method" : "Basic"<br />
},<br />
{<br />
"method": "Form",<br />
}<br />
],<br />
"authorization":<br />
[<br />
"sap.xse.test::Execute",<br />
"sap.xse.test::Admin"<br />
]<br />
"rewrite_rules" :<br />
[{<br />
"source" : "...",<br />
"target" : "..."<br />
}],<br />
"mime_mapping" :<br />
[<br />
{<br />
"extension":"jpg", "mimetype":"image/jpeg"<br />
}<br />
],<br />
"force_ssl" : true,<br />
"enable_etags":false<br />
"exposed" : true,<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 53
}<br />
The exposed keyword enables you define if content in a package (and its subpackages) is to be made available by<br />
HTTP to client requests. Values are Boolean true or false. If no value is set for exposed, the default setting (false)<br />
applies.<br />
authentication<br />
}<br />
{<br />
"authentication" :<br />
[<br />
{<br />
"method": "LogonTicket",<br />
},<br />
{<br />
"method" : "Basic",<br />
},<br />
{<br />
"method": "Form",<br />
}<br />
],<br />
The authentication keyword enables you to define the authentication method to use for Browser requests either<br />
at the application level or for single packages in an application. <strong>SAP</strong> <strong>HANA</strong> Extended Application Services support<br />
the following logon authentication mechanisms:<br />
Note: You can specify multiple authentication methods in the application-access file.<br />
● Basic authentication<br />
Logon with a recognized database user name and password.<br />
● <strong>SAP</strong> logon ticket<br />
<strong>SAP</strong> logon tickets enable single sign-on across <strong>SAP</strong> boundaries; <strong>SAP</strong> logon tickets can be also be used as<br />
authentication for access to third-party applications.<br />
● Form-based authentication<br />
Redirect the logon request to a form to fill in, for example, a Web page.<br />
If you use the authentication in the .xsaccess file, you must specify the authentication method to apply, for<br />
example, basic or <strong>SAP</strong> logon ticket. If you use the authentication keyword in the application-access file, but do not<br />
set an authentication method, your .xsaccess file is a valid JSON file but is not a semantically valid .xsaccess<br />
file and will return a parsing validation error . If you do not set the authentication keyword, your application applies<br />
the default basic authentication method (user name and password) to enable access to data.<br />
54<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
Note: You can disable authentication checks with the null options, as follows: {"authentication" :<br />
null}.<br />
authorization<br />
{<br />
}<br />
"authorization":<br />
[<br />
"sap.xse.test::Execute",<br />
"sap.xse.test::Admin"<br />
]<br />
The authorization keyword in the .xsaccess file enables you to specify which authorization level is required for<br />
access to a particular application package, for example, execute or admin on the package sap.xse.text.<br />
Note: The authorization levels you can choose from are defined in the .xsprivileges file for the<br />
package, for example, "execute" for basic privileges, or "admin" for administrative privileges on the<br />
specified package. If you use the authorization keyword in the .xsaccess file, for example, to require<br />
“execute” privileges for a specific application package, you must create a .xsprivileges file for the<br />
same application package (or a parent package higher up the hierarchy, in which you define the “execute”<br />
privilege level declared in the .xsaccess file.<br />
rewrite_rules<br />
}<br />
{<br />
"rewrite_rules" :<br />
[{<br />
"source" : "...",<br />
"target" : "..."<br />
}]<br />
The rewrite_rules keyword enables you hide the details of internal URL paths from external users, clients, and<br />
search engines. Any rules specified affect the local application where the .xsaccess file resides (and any<br />
subpackage, assuming the subpackages do not have their own .xsaccess files); it is not possible to define global<br />
rewrite rules. URL rewrite rules are specified as a source-target pair where the source is written in the JavaScript<br />
regex syntax and the target is a simple string where references to found groups can be inserted using<br />
$groupnumber.<br />
mime_mapping<br />
{<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
"mime_mapping" :<br />
[<br />
{<br />
"extension":"jpg", "mimetype":"image/jpeg"<br />
}<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 55
}<br />
]<br />
The mime_mapping keyword enables you to define how to map certain file suffixes to required MIME types. For<br />
example, you can map files with the .jpg file extension to the MIME type image/jpeg.<br />
force_ssl<br />
}<br />
{<br />
"force_ssl" : true,<br />
The force_ssl keyword enables you to refuse Browser requests that do not use secure HTTP (SSL/HTTPS) for<br />
client connections. If no value is set for exposed, the default setting (false) applies and non-secured connections<br />
(HTTP) are allowed.<br />
enable_etags<br />
}<br />
{<br />
"enable_etags" : true,<br />
You can allow or prevent the generation of entity tags (etags) for static Web content using the enable_etags<br />
keyword. If no value is set, the default setting (true) applies, in which case etags are generated. Etags are used to<br />
improve caching performance, for example, so that the same data is not resent from the server if no change has<br />
occurred since the last time a request for the same data was made.<br />
4.4.5 Application-Access URL Rewrite Rules<br />
Rewriting URLs enables you to hide internal URL path details from external users, clients, and search engines. You<br />
define URL rewrite rules in the application-access file (.xsaccess) for each application or for an application<br />
hierarchy (an application package and its subpackages).<br />
The rewrite rules you define in the .xsaccess file apply only to the local application to which the .xsaccess file<br />
belongs; it is not possible to define global rules to rewrite URLs. Rules are specified as a source-target pair where<br />
the source is written in the JavaScript regex syntax, and the target is a simple string where references to found<br />
groups can be inserted using $groupnumber.<br />
The following examples show how to use a simple set of rewrite rules to hide internal URLs from requesting clients<br />
and users.<br />
The first example illustrates the package structure that exists in the repository for a given application; the<br />
structure includes the base package apptest, the subpackages subpackage1 and subpackage2, and several<br />
other subpackages:<br />
56<br />
sap---apptest<br />
|---logic<br />
| |---users.xsjs<br />
| |---posts.xsjs<br />
|---posts<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
| |---2011...<br />
|---subpackage1<br />
| |---image.jpg<br />
|---subpackage2<br />
| |---subsubpackage<br />
| | |---secret.txt<br />
| |---script.xsjs<br />
|---subpackage3<br />
| |---internal.file<br />
|---users<br />
| |---123...<br />
|---.xsapp<br />
|---.xsaccess<br />
|---index.html<br />
The application-access file for the package apptest (and its subpackages) includes the following rules for<br />
rewriting URLs used in client requests:<br />
{<br />
}<br />
"rewrite_rules": [<br />
{<br />
"source": "/users/(\\d+)/",<br />
"target": "/logic/users.xsjs?id=$1"<br />
},<br />
{<br />
"source": "/posts/(\\d+)/(\\d+)/(\\d+)/",<br />
"target": "/logic/posts.xsjs?year=$1&month=$2&day=$3"<br />
}<br />
]<br />
Assuming we have the package structure and URL rewrite rules illustrated in the previous examples, the following<br />
valid URLs would be exposed; bold URLs require authentication:<br />
/sap/apptest/<br />
/sap/apptest/index.html<br />
/sap/apptest/logic/users.xsjs<br />
/sap/apptest/logic/posts.xsjs<br />
The rewriting of the following URLs would be allowed:<br />
/sap/apptest/users/123/ ==> /sap/appTest/logic/users.xsjs?id=123<br />
/sap/apptest/posts/2011/10/12/ ==> /sap/appTest/logic/posts.xsjs?<br />
year=2011&month=10&day=12<br />
4.4.6 Enabling Access to <strong>SAP</strong> <strong>HANA</strong> XS Application<br />
Packages<br />
The application-access file enables you to specify who or what is authorized to access the content exposed by the<br />
application package and what content they are allowed to see.<br />
You can use a set of keywords in the application-access file .xsaccess to specify if authentication is required to<br />
enable access to package content, which data is exposed, and if rewrite rules are in place to hide target and<br />
source URLs, for example, from users and search engines. You can also specify what, if any, level of authorization<br />
is required for the package and whether SSL is mandatory for client connections.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 57
1. Create the application access file.<br />
The application-access file must be a JSON-compliant file with the file suffix .xsaccess. Note that the<br />
application-access file does not have a name before the dot (.); it only has the suffix .xsaccess.<br />
Create a file called .xsaccess and place it in the package containing the application to which you want to<br />
enable accesss. A basic .xsaccess file must, as the very least, contain a set of curly brackets, for example,<br />
{}. Note that the .xsaccess file uses keyword-value pairs to set access rules; if a mandatory keyword-value<br />
pair is not set, then the default value is assumed.<br />
2. Enable application access to data.<br />
You use the expose keyword to enable or disable access to content at a package or subpackage level.<br />
{<br />
}<br />
"exposed" : true<br />
3. Define the application authentication method.<br />
You use the authentication keyword to define how to manage the authentication process for requests to<br />
access package content, for example, <strong>SAP</strong> logon ticket, form-based logon, or a basic user name and<br />
password .<br />
{<br />
}<br />
"authentication" :<br />
[<br />
{ "method" : "Basic" }<br />
]<br />
4. Specify the application privileges.<br />
Use the authorization keyword in the .xsaccess file to specify which authorization level is required by a user<br />
for access to a particular application package. The authorization levels you can choose from are defined in<br />
the .xsprivileges file, for example, "execute" for basic privileges or "admin" for administrative privileges<br />
on the specified package.<br />
{<br />
}<br />
"authorization":<br />
[<br />
"sap.xse.test::Execute",<br />
"sap.xse.test::Admin"<br />
]<br />
5. Specify the client connection security.<br />
You use the force_ssl keyword to enforce the use of secure HTTP (SSL/HTTPS) for client connections.<br />
Browser requests that do not use SSL/HTTPS are refused and the 403 Forbidden page is displayed.<br />
{<br />
}<br />
Note: You need to ensure the <strong>SAP</strong> Web Dispatcher is configured to accept and process HTTPS<br />
requests.<br />
"force_ssl" : true<br />
6. Define the MIME mapping to be used for specific file extensions. (Optional)<br />
58<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
You use the mime_mapping keyword to map specific file extensions (for example, .jpg or .png) to a<br />
particular Multipurpose Internet Mail Extensions (MIME) type.<br />
{<br />
}<br />
"mime_mapping" :<br />
[<br />
{<br />
"extension":"jpg",<br />
"mimetype":"image/jpeg"<br />
}<br />
]<br />
7. Prevent the generation of entity tags. (Optional)<br />
You use the enable_etags keyword to prevent the generation of entity tags (etags) for static Web content.<br />
{<br />
}<br />
"enable_etags":false<br />
8. Specify which, if any, URLs must be rewritten. (Optional)<br />
You use the rewrite_rules keyword to hide details of internal URL paths from external users, clients, and<br />
search engines.<br />
{<br />
}<br />
"rewrite_rules" :<br />
[<br />
{<br />
"source" : "...",<br />
"target" : "..."<br />
}<br />
]<br />
9. Save the .xsaccess file and place it in the package with which you want to associate the rules you have<br />
defined.<br />
10. Commit the file to the repository and activate it.<br />
In the Project Navigator view, right click the object you want to activate and choose Team > Activate in<br />
the popup menu.<br />
Related Links<br />
Application-Access File Keyword Options [page 53]<br />
The application-access (.xsaccess) file enables you to specify whether or not to expose package content,<br />
which authentication method is used to grant access, and what content is visible.<br />
4.4.7 The Application-Privileges File<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the application-privileges (.xssprivileges) file<br />
can be used to create or define the authorization privileges required for access to an <strong>SAP</strong> <strong>HANA</strong> XS application,<br />
for example, to start the application or to perform administrative actions on an application. These privileges can<br />
be checked by an application at runtime.<br />
The application-privileges file has only the file extension .xsprivileges; it does not have a name and is<br />
formatted according to JSON rules. Multiple .xsprivileges files are allowed, but only at different levels in the<br />
package hierarchy; you cannot place two .xsprivileges files in the same application package. The package<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 59
privileges defined in a .xsprivileges file are bound to the package to which the .xsprivileges file belongs<br />
and can only be used in this package and its subpackages.<br />
Inside the .xsprivileges file, a privilege is defined by specifying an entry name with an optional description.<br />
This entry name is then automatically prefixed with the package name to form the unique privilege name, for<br />
example, sap.hana::Execute.<br />
As an application privilege is created during activation of an .xsprivileges file, the only user who has the<br />
privilege by default is the _SYS_REPO user. To grant or revoke the privilege to (or from) other users you must use<br />
the GRANT_APPLICATION_PRIVILEGE or REVOKE_APPLICATION_PRIVILEGE procedure in the _SYS_REPO<br />
schema.<br />
Note: The .xsprivileges file lists the authorization levels that are available for access to an application<br />
package; the .xsaccess file defines which authorization level is assigned to which application package.<br />
The <strong>SAP</strong> <strong>HANA</strong> XS Application-Privileges File<br />
The following example shows the composition and structure of a basic <strong>SAP</strong> <strong>HANA</strong> XS application-<br />
privileges file.<br />
{<br />
"privileges" :<br />
[<br />
{ "name" : "Execute", "description" : "Basic execution<br />
privilege" },<br />
{ "name" : "Admin", "description" : "Administration<br />
privilege" },<br />
]<br />
}<br />
In the example above, if the application-privileges file is located in the application package<br />
sap.hana.xse, then the following privileges are created:<br />
● sap.hana.xse::Execute<br />
● sap.hana.xse::Admin<br />
Note: The privileges defined apply to the package where the .xsprivileges file is located as well<br />
as any packages further down the package hierarchy unless an additional .xsprivileges file is<br />
present, for example, in a subpackage. The privileges do not apply to packages that are not in the<br />
specified package path, for example, sap.hana.app1.<br />
For the example above, the following Grant procedure would be used:<br />
call<br />
"_SYS_REPO"."GRANT_APPLICATION_PRIVILEGE"('"sap.hana.xse::Execute"',<br />
'')<br />
4.4.8 Create an <strong>SAP</strong> <strong>HANA</strong> XS Application Privileges File<br />
The application-privileges (.xssprivileges) file can be used to grant authorization levels for an application, for<br />
example, to start the application or perform administrative actions on an application.<br />
60<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
1. If you have not already done so, create a root package for your new application, for example,<br />
MyApplication.<br />
2. If you have not already done so, create an application descriptor for your new application and place it in the<br />
root package you created in the previous step.<br />
The application descriptor is the core file that you use to describe an application's availability within <strong>SAP</strong><br />
<strong>HANA</strong> Extended Application Services. The application-descriptor file has no contents and no name; it only has<br />
the file extension .xsapp.<br />
Note: For backward compatibility, content is allowed in the .xsapp file but ignored.<br />
3. If you have not already done so, create an application-access file for your new application and place it in the<br />
package to which you want to grant access.<br />
The application-access file does not have a name; it only has the file extension .xsaccess. The contents of<br />
the .xsaccess file must be formatted according to JavaScript Object Notation (JSON) rules and associated<br />
with the package it belongs to. The rules defined in the .xsaccess file apply to the package it resides in as<br />
well as any subpackages lower in the package hierarchy.<br />
Note:<br />
Use the authorization keyword in the .xsaccess file to specify which authorization level is to be<br />
granted to a particular application package. The authorization levels you can choose from are defined<br />
in the application-privileges file (.xsprivileges), for example, "execute" for basic privileges, or<br />
"admin" for administrative privileges on the specified package.<br />
4. Create the application-privileges file.<br />
The application-privileges file does not have a name; it only has the file extension .xsprivileges. The<br />
contents of the .xsprivileges file must be formatted according to JavaScript Object Notation (JSON)<br />
rules. Multiple .xsprivileges files are allowed, but only at different levels in the package hierarchy; you<br />
cannot place two .privileges files in the same application package. The privileges defined in<br />
a .xsprivileges file are bound to the package to which the file belongs and can only be applied to this<br />
package and its subpackages.<br />
5. Define the application privileges.<br />
Inside the .xsprivileges file, a privilege is defined for an application package by specifying an entry name<br />
with an optional description. This entry name is then automatically prefixed with the package name to form<br />
the unique privilege name, for example, sap.hana::Execute. The unique privilege name can be used in<br />
multiple .xsprivileges files in different packages, since they are all different privileges.<br />
Note: The .xsprivileges file lists the authorization levels available for granting to an application<br />
package; the .xsaccess file defines which authorization level is assigned to which application<br />
package.<br />
{<br />
"privileges" :<br />
[<br />
{ "name" : "Execute", "description" : "Basic execution<br />
privilege" },<br />
{ "name" : "Admin", "description" : "Adminstration<br />
privilege" },<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 61
}<br />
]<br />
6. Save and activate your changes and additions.<br />
4.5 Tutorial: My First <strong>SAP</strong> <strong>HANA</strong> Application<br />
This tutorial shows you how <strong>SAP</strong> <strong>HANA</strong> development is done in the <strong>SAP</strong> <strong>HANA</strong> studio, including setting up a<br />
project, and developing a simple JavaScript file to extract data from the database.<br />
Though extremely simple, the tutorial shows the development process for programming all types of applications.<br />
The project creates server-side JavaScript code that retrieves data by executing SQL in the database, and then<br />
returns the data to the client, which in this case is a browser. The project can be viewed as adhering to the model-<br />
view-controller architecture:<br />
● Model: You have (dummy) data in the database, which we can extract via SQL.<br />
● Controller: You have JavaScript code that controls the extraction of the data and delivers it to the view.<br />
● View: You have a simple browser that calls the JavaScript code and simply displays the data.<br />
4.5.1 Open the Development Perspective<br />
Before you do anything, you have to start the <strong>SAP</strong> <strong>HANA</strong> studio and open the <strong>SAP</strong> <strong>HANA</strong> Development<br />
perspective.<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio. The first screen you see is the Welcome screen, with quick links to the main <strong>SAP</strong><br />
<strong>HANA</strong> perspectives and to the documentation.<br />
62<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
2. Select Open Development.<br />
The default <strong>SAP</strong> <strong>HANA</strong> Development perspective contains three views on the left for navigating <strong>SAP</strong> <strong>HANA</strong><br />
and the repository, which holds the objects that you will create. In addition, the editor area is on the right,<br />
where you will build your objects.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Development Perspective [page 25]<br />
4.5.2 Add a System<br />
You need to add a connection to the development <strong>SAP</strong> <strong>HANA</strong> system you will be working with.<br />
1. In the Navigator view, right-click anywhere in the view and select Add System.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 63
2. Enter the following fields for the <strong>SAP</strong> <strong>HANA</strong> system:<br />
64<br />
○ Server name<br />
○ Instance number on that server<br />
○ A display name for this system. When you start working with a lot of systems, you will want to have a way<br />
to label the systems in the <strong>SAP</strong> <strong>HANA</strong> studio. Enter Development System.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
3. Select Next.<br />
4. Enter a user name and password for the connection, and select Finish.<br />
After adding the system, you will see the system in the Navigator view.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 65
4.5.3 Add a Workspace<br />
After you add a system, you need to specify where on your workstation you will be saving development files while<br />
working with this system.<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> Repositories view, click in the upper-right of the view.<br />
2. Provide the following:<br />
○ <strong>SAP</strong> <strong>HANA</strong> system, which is the same system you just created.<br />
○ Workspace name, which can be anything you like. For this tutorial, enter DevWS.<br />
A folder with this name is created below the workspace root.<br />
○ Workspace root, which can be anywhere on your workstation. For this tutorial, create a folder at C:<br />
3. Click Finish.<br />
66<br />
\<strong>SAP</strong><strong>HANA</strong>workspaces and make this the root.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
In the <strong>SAP</strong> <strong>HANA</strong> Repositories view, you will see your workspace, which enables you to browse the repository of<br />
the system tied to this workspace. You will see the repository's packages, displayed as folders.<br />
At the same time, a folder will be added to your file system to hold all your development files.<br />
4.5.4 Add a Project<br />
Now that you've set up your development environment for your <strong>SAP</strong> <strong>HANA</strong> system, you can add an Eclipse<br />
project to contain all the development objects you want to create.<br />
There are a variety of project types for different types of development objects. Generally, these projects types<br />
import necessary libraries for working with specific types of development objects. Here, you will create an XS<br />
Project.<br />
1. From the menu, select File New Project .<br />
2. Under <strong>SAP</strong> <strong>HANA</strong> Development, select XS Project, and select Next.<br />
3. Enter the following for the project:<br />
○ Name: Enter mycompany.myorg.testing.<br />
Since Eclipse project names must be unique within the same Eclipse workspace, a good convention is to<br />
use the fully qualified package name as the project name.<br />
○ Project Location: You can keep this as the default Eclipse workspace.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 67
4. Select Finish.<br />
Now, in the Project Explorer view, you have a project that is ready to be shared, that is, associated with your<br />
workspace.<br />
4.5.5 Share Your Project<br />
After creating a project, you must associate it with a workspace, which enables the project files to be saved to the<br />
repository of your development <strong>SAP</strong> <strong>HANA</strong> system.<br />
1. In the Project Explorer view, right-click on the project, and select Team Share Project .<br />
68<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
Since you only have one workspace, the wizard selects it for you. If you had several workspaces, you would<br />
choose with which one you wanted to share your project.<br />
The dialog also shows the Current project location (the current location of your project, in the Eclipse<br />
workspace), and the New project location (where your project will be copied so it can be associated with the<br />
repository workspace).<br />
Also, since Add project folder as subpackage is checked, subpackages will be created based on the name of<br />
your project.<br />
2. Click Finish.<br />
Now your project appears in the Project Explorer view associated with your workspace.<br />
The .project file is shown with an asterisk , which indicates that the file has changed but has yet to be<br />
committed, or saved, to the repository.<br />
3. Right-click on the project, and select Team Commit . This adds your project and its files to the<br />
repository, though only you can see them. The .project file is now displayed with a diamond, , indicating<br />
that the latest version on your workstation has been committed.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 69
In addition, the <strong>SAP</strong> <strong>HANA</strong> Repositories view shows that a new hierarchy of packages has been created based<br />
on the name of your project, mycompany.myorg.testing.<br />
4.5.6 Write Server-Side JavaScript<br />
Now let's write some code. As a first step, to make sure everything is working OK, you will simply output Hello,<br />
World!.<br />
You will have to create three files:<br />
● .xsjs: This contains your code.<br />
● .xsapp: This indicates that everything in your package can be exposed via HTTP. You still need to explicitly<br />
expose the content and assign access controls.<br />
● .xsaccess: Exposes your content, meaning it can be accessed via HTTP, and assigned access controls.<br />
1. Right-click your project, and select New Other .<br />
2. Select <strong>SAP</strong> <strong>HANA</strong> Development XS JavaScript Source File .<br />
3. In File name, call your JavaScript file MyFirstSourceFile.xsjs, and select Finish.<br />
The file, which is blank, opens in the JavaScript editor.<br />
4. In the MyFirstSourceFile.xsjs file, enter the following code:<br />
$.response.contentType = "text/html";<br />
$.response.setBody( "Hello, World !");<br />
This uses the <strong>SAP</strong> <strong>HANA</strong> XS JavaScript API's response object to write out HTML. By typing $. you have<br />
access to the API's objects.<br />
5. Add a blank file called .xsapp (no name, just a file extension) by right-clicking to the root of your project.<br />
70<br />
More on this later.<br />
To add a file, right-click the project and select New File , enter a file name, and select Finish.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
6. Add a file called .xsaccess (no name, just a file extension), and copy the following code:<br />
{<br />
}<br />
"exposed" : true,<br />
"authentication" :<br />
[<br />
{ "method" : "Basic" }<br />
]<br />
This code exposes the contents via HTTP, and requires you to log in with your <strong>SAP</strong> <strong>HANA</strong> credentials to<br />
access the file.<br />
7. Right-click on the project, and select Team Commit . This adds your four new files<br />
(.xsjs, .xsapp, .xsaccess and .project) to the repository, though only you can see the files and no one<br />
can run them.<br />
8. Right-click on the project, and select Team Activate . This publishes your work and you can now test it.<br />
To access your JavaScript code, open a browser and enter the URL:<br />
http://myServer:8000/mycompany/myorg/testing/MyFirstSourceFile.xsjs<br />
Note:<br />
● Change the server name to your server.<br />
● The port is 80 plus two digits for your instance. If your instance is 00, then the port is 8000.<br />
You should get the following:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 71
After logging in with your <strong>SAP</strong> <strong>HANA</strong> user name and password, you should get the following:<br />
4.5.7 Retrieve Data<br />
To make things more interesting, let's make a call to the database via the JavaScript and then display the results.<br />
You will be using the SQL statement:<br />
select * from DUMMY<br />
This is test SQL to check connectivity, and returns one row with one field called DUMMY, whose value is X.<br />
1. In MyFirstSourceFile.xsjs, delete or comment out all your existing code.<br />
2. Add the following code:<br />
$.response.contentType = "text/html";<br />
var output = "Hello, World !";<br />
var conn = $.db.getConnection();<br />
var pstmt = conn.prepareStatement( "select * from DUMMY" );<br />
var rs = pstmt.executeQuery();<br />
if (!rs.next()) {<br />
$.response.setBody( "Failed to retrieve data" );<br />
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;<br />
} else {<br />
output = output + "This is the response from my SQL: " +<br />
rs.getString(1);<br />
}<br />
rs.close();<br />
pstmt.close();<br />
conn.close();<br />
$.response.setBody(output);<br />
3. Save the file.<br />
4. Commit the file by right-clicking the file and selecting Team Commit .<br />
5. Activate the file by right-clicking the file and selecting Team Activate .<br />
In your browser, refresh the page. You should get the following:<br />
72<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Your Application<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 73
5 Setting Up the Persistence Model<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the persistence model defines the schema, tables,<br />
and views that specify what data to make accessible and how. The persistence model is mapped to the<br />
consumption model that is exposed to client applications and users, so that data can be analyzed and displayed.<br />
<strong>SAP</strong> <strong>HANA</strong> XS enables you to create database schema, tables, views, and sequences as design-time files in the<br />
repository. Repository files can be read by applications that you develop.<br />
Note: All repository files including your view definition can be transported (along with tables, schema, and<br />
sequences) to other <strong>SAP</strong> <strong>HANA</strong> systems, for example, in a delivery unit. A delivery unit is the medium <strong>SAP</strong><br />
<strong>HANA</strong> provides to enable you to assemble all your application-related repository artifacts together into an<br />
archive that can be easily exported to other systems.<br />
You can also set up data-provisioning rules and save them as design-time objects so that they can be included in<br />
the delivery unit that you transport between systems.<br />
As part of the process of setting up the basic persistence model for <strong>SAP</strong> <strong>HANA</strong> XS, you perform the following<br />
tasks:<br />
● Create a schema.<br />
Define a design-time schema and maintain the schema definition in the repository. The transportable schema<br />
has the file extension .hdbschema, for example, MYSCHEMA.hdbschema<br />
● Create a table.<br />
Define a design-time table and maintain the table definition in the repository. The transportable table has the<br />
file extension .hdbtable, for example, MYTABLE.hdbtable<br />
● Create a view.<br />
Define a design-time view and maintain the view definition in the repository. The transportable view has the<br />
file extension .hdbview, for example, MYVIEW.hdbview<br />
● Create a sequence.<br />
Define a design-time sequence and maintain the sequence definition in the repository. The transportable<br />
sequence has the file extension .hdbsequence, for example, MYSEQUENCE.hdbsequence<br />
● Import table content<br />
74<br />
Define data-provisioning rules that enable you to import data from comma-separated values (CSV) files into<br />
<strong>SAP</strong> <strong>HANA</strong> tables using the <strong>SAP</strong> <strong>HANA</strong> XS table-import feature. The complete configuration can be included<br />
in a delivery unit and transported between <strong>SAP</strong> <strong>HANA</strong> systems.<br />
Note: On activation of a repository file, the file suffix, for example, .hdbview, .hdbschema,<br />
or .hdbtable, is used to determine which runtime plugin to call during the activation process. The plugin<br />
reads the repository file selected for activation, for example, a table, sees the object descriptions in the<br />
file, and creates the appropriate runtime object.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
5.1 Schema<br />
Relational databases contain a catalog that describes the various elements in the system. The catalog divides the<br />
database into sub-databases known as schema. A database schema enables you to logically group together<br />
objects such as tables, views, and stored procedures. Without a defined schema, you cannot write to the catalog.<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database schema as a<br />
transportable design-time file in the repository. Repository files can be read by applications that you develop.<br />
If your application refers to the repository (design-time) version of a schema rather than the runtime version in<br />
the catalog, for example, by using the explicit path to the repository file (with suffix), any changes to the<br />
repository version of the file are visible as soon as they are committed to the repository. There is no need to wait<br />
for the repository to activate a runtime version of the schema.<br />
If you want to define a transportable schema using the design-time hdbschema specifications, use the<br />
configuration schema illustrated in the following example:<br />
string schema_name<br />
The following example shows the contents of a valid transportable schema-definition file for a schema called<br />
MYSCHEMA:<br />
schema_name=”MYSCHEMA”;<br />
The schema is stored in the repository with the schema name MYSCHEMA as the file name and the<br />
suffix .hdbschema, for example, MYSCHEMA.hdbschema.<br />
Schema Activation<br />
If you want to create a schema definition as a design-time object, you must create the schema as a flat file. You<br />
save the file containing the schema definition with the suffix .hdbschema in the appropriate package for your<br />
application in the <strong>SAP</strong> <strong>HANA</strong> repository. You can activate the design-time objects at any point in time.<br />
Note: On activation of a repository file, the file suffix, for example, .hdbschema, is used to determine<br />
which runtime plugin to call during the activation process. The plug-in reads the repository file selected for<br />
activation, parses the object descriptions in the file, and creates the appropriate runtime objects.<br />
If you activate a schema-definition object in <strong>SAP</strong> <strong>HANA</strong>, the activation process checks if a schema with the same<br />
name already exists in the <strong>SAP</strong> <strong>HANA</strong> repository. If a schema with the specified name does not exist, the<br />
repository creates a schema with the specified name and makes _SYS_REPO the owner of the new schema.<br />
Note: The schema cannot be dropped even if the deletion of a schema object is activated.<br />
If you define a schema in <strong>SAP</strong> <strong>HANA</strong> XS, note the following important points regarding the schema name:<br />
● Name mapping<br />
The schema name must be identical to the name of the corresponding repository object.<br />
● Naming conventions<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 75
The schema name must adhere to the <strong>SAP</strong> <strong>HANA</strong> rules for database identifiers.<br />
● Name usage<br />
The Data Definition Language (DDL) rendered by the repository contains the schema name as a delimited<br />
identifier.<br />
5.2 Creating Schemas<br />
A schema defines the container that holds database objects such as tables, views, and stored procedures.<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database schema as a design-<br />
time file in the repository.<br />
To create a schema definition file in the repository, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Open the Project Explorer view.<br />
4. Create the schema definition file.<br />
Browse to the folder in your project workspace where you want to create the new schema-definition file and<br />
perform the following tasks:<br />
a) Right-click the folder where you want to save the schema-definition file and choose New in the contextsensitive<br />
popup menu.<br />
b) Enter the name of the schema in the File Name box and add the file suffix .hdbschema, for example,<br />
MYSCHEMA.hdbschema.<br />
c) Choose Finish to save the new schema in the repository.<br />
5. Define the schema name.<br />
To edit the schema file, in the Project Explorer view double-click the schema file you created in the previous<br />
step, for example, MYSCHEMA.hdbschema, and add the schema-definition code to the file:<br />
Note: The following code example is provided for illustration purposes only.<br />
schema_name=”MYSCHEMA”<br />
6. Save the schema file.<br />
7. Commit the changes to the repository.<br />
a) Locate and right-click the new schema file in the Project Explorer view.<br />
b) In the context-sensitive pop-up menu, choose Team Commit .<br />
5.3 Tables<br />
In the <strong>SAP</strong> <strong>HANA</strong> database, as in other relational databases, a table is a set of data elements that are organized<br />
using columns and rows. A database table has a specified number of columns, defined at the time of table<br />
76<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
creation, but can have any number of rows. Database tables also typically have meta-data associated with them;<br />
the meta-data might include constraints on the table or on the values within particular columns.<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database table as a designtime<br />
file in the repository. All repository files including your table definition can be transported to other <strong>SAP</strong> <strong>HANA</strong><br />
systems, for example, in a delivery unit.<br />
Note: A delivery unit is the medium <strong>SAP</strong> <strong>HANA</strong> provides to enable you to assemble all your applicationrelated<br />
repository artifacts together into an archive that can be easily exported to other systems.<br />
If your application is configured to use the design-time version of a database table in the repository rather than<br />
the runtime version in the catalog, any changes to the repository version of the table are visible as soon as they<br />
are committed to the repository. There is no need to wait for the repository to activate a runtime version of the<br />
table.<br />
The following code illustrates a simple example of a design-time table definition:<br />
table.schemaName = "MYSCHEMA";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20;<br />
comment = "dummy comment";},<br />
{name = "Col2"; sqlType = INTEGER; nullable = false;},<br />
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;<br />
defaultValue = "Defaultvalue";},<br />
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 2;<br />
scale = 3;}];<br />
table.indexes = [<br />
{name = "MYINDEX1"; unique = true; indexColumns = ["Col2"];},<br />
{name = "MYINDEX2"; unique = true; indexColumns = ["Col1", "Col4"];}];<br />
table.primaryKey.pkcolumns = ["Col1", "Col2"];<br />
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<br />
containing the table dimensions with the suffix .hdbtable, for example, MYTABLE.hdbtable. The new file is<br />
located in the package hierarchy you establish in the <strong>SAP</strong> <strong>HANA</strong> repository. You can activate the repository files at<br />
any point in time.<br />
Note: On activation of a repository file, the file suffix, for example, .hdbtable, is used to determine which<br />
runtime plugin to call during the activation process. The plugin reads the repository file selected for<br />
activation, in this case a table, parses the object descriptions in the file, and creates the appropriate<br />
runtime objects.<br />
5.4 Creating Tables<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database table as a designtime<br />
file in the repository.<br />
To create a table file in the repository, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Open the Project Explorer view.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 77
4. Create the table file.<br />
Browse to the folder in your project workspace where you want to create the new table file and perform the<br />
following tasks:<br />
a) Right-click the folder where you want to save the table file and choose New in the context-sensitive popup<br />
menu.<br />
b) Enter the name of the table in the File Name box and add the file suffix .hdbtable, for example,<br />
MYTABLE.hdbtable.<br />
c) Choose Finish to save the new table in the repository.<br />
5. Define the table.<br />
To edit the table file, in the Project Explorer view double-click the table file you created in the previous step, for<br />
example, MYTABLE.hdbtable, and add the table-definition code to the file:<br />
Note: The following code example is provided for illustration purposes only.<br />
table.schemaName = "MYSCHEMA";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "Col1"; sqlType = VARCHAR; nullable = false; length = 20;<br />
comment = "dummy comment";},<br />
{name = "Col2"; sqlType = INTEGER; nullable = false;},<br />
{name = "Col3"; sqlType = NVARCHAR; nullable = true; length = 20;<br />
defaultValue = "Defaultvalue";},<br />
{name = "Col4"; sqlType = DECIMAL; nullable = false; precision = 2;<br />
scale = 3;}];<br />
table.indexes = [<br />
{name = "MYINDEX1"; unique = true; indexColumns = ["Col2"];},<br />
{name = "MYINDEX2"; unique = true; indexColumns = ["Col1",<br />
"Col4"];}];<br />
table.primaryKey.pkcolumns = ["Col1", "Col2"];<br />
6. Save the table file.<br />
7. Commit the changes to the repository.<br />
a) Locate and right-click the new table file in the Project Explorer view.<br />
b) In the context-sensitive pop-up menu, choose Team Commit .<br />
5.5 Sequences<br />
A sequence is a database object that generates a serial list of unique numbers. You can use sequence definitions<br />
in mappings to generate unique numbers while transforming and moving data to your target system.<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database sequence as a<br />
transportable design-time file in the repository. Repository files can be read by applications that you develop.<br />
You can use database sequences to perform the following operations:<br />
● Generate unique, primary key values<br />
● Coordinate keys across multiple rows or tables<br />
78<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
If you want to define a transportable sequence using the design-time sequence specifications, use the<br />
configuration schema illustrated in the following example.<br />
string schema;<br />
int32 increment_by(default=1);<br />
int32 start_with(default=-1);<br />
optional int32 maxvalue;<br />
bool nomaxvalue(default=false);<br />
optional int32 minvalue;<br />
bool nominvalue(default=false);<br />
optional bool cycles;<br />
optional string reset_by;<br />
bool public(default=false);<br />
optional string depends_on_table;<br />
optional string depends_on_view;<br />
The following example shows the contents of a valid sequence-definition file for a sequence called MYSEQUENCE.<br />
schema= "TEST_DUMMY";<br />
start_with= 10;<br />
maxvalue= 30;<br />
nomaxvalue=false;<br />
minvalue= 1;<br />
nominvalue=true;<br />
cycles= false;<br />
reset_by= "SELECT \"Col2\" FROM \"TEST_DUMMY\".<br />
\"com.sap.test.tables::MY_TABLE\" WHERE \"Col2\"='12'";<br />
depends_on_table= "com.sap.test.tables::MY_TABLE";<br />
The sequence is stored in the repository with the suffix hdbsequence, for example, MYSEQUENCE.hdbsequence.<br />
If you activate a sequence-definition object in <strong>SAP</strong> <strong>HANA</strong> XS, the activation process checks if a sequence with the<br />
same name already exists in the <strong>SAP</strong> <strong>HANA</strong> repository. If a sequence with the specified name does not exist, the<br />
repository creates a sequence with the specified name and makes _SYS_REPO the owner of the new sequence.<br />
Note: The sequence cannot be dropped even if the deletion of a sequence object is activated.<br />
5.6 Creating Sequences<br />
A database sequence generates a serial list of unique numbers that you can use while transforming and moving<br />
data to between systems.<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database sequence as a<br />
design-time file in the repository.<br />
To create a sequence definition file in the repository, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Open the Project Explorer view.<br />
4. Create the sequence-definition file.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 79
Browse to the folder in your project workspace where you want to create the new sequence-definition file and<br />
perform the following tasks:<br />
a) Right-click the folder where you want to save the sequence-definition file and choose New in the contextsensitive<br />
popup menu.<br />
b) Enter the name of the sequence in the File Name box and add the file suffix .hdbsequence, for example,<br />
MYSEQUENCE.hdbsequence.<br />
c) Choose Finish to save the new sequence in the repository.<br />
5. Define the sequence properties.<br />
To edit the sequence file, in the Project Explorer view double-click the sequence file you created in the<br />
previous step, for example, MYSEQUENCE.hdbsequence, and add the sequence code to the file:<br />
schema= "TEST_DUMMY";<br />
start_with= 10;<br />
maxvalue= 30;<br />
nomaxvalue=false;<br />
minvalue= 1;<br />
nominvalue=true;<br />
cycles= false;<br />
reset_by= "SELECT \"Col2\" FROM \"TEST_DUMMY\".<br />
\"com.sap.test.tables::MY_TABLE\" WHERE \"Col2\"='12'";<br />
depends_on_table= "com.sap.test.tables::MY_TABLE";<br />
6. Save the sequence file.<br />
7. Commit the changes to the repository.<br />
a) Locate and right-click the new sequence file in the Project Explorer view.<br />
b) In the context-sensitive pop-up menu, choose Team Commit .<br />
5.7 SQL Views<br />
In SQL, a view is a virtual table based on the dynamic results returned in response to an SQL statement. Every<br />
time a user queries an SQL view, the database uses the view's SQL statement to recreate the data specified in the<br />
SQL view. The data displayed in an SQL view can be extracted from one or more database tables.<br />
An SQL view contains rows and columns, just like a real database table; the fields in an SQL view are fields from<br />
one or more real tables in the database. You can add SQL functions, for example, WHERE or JOIN statements, to a<br />
view and present the resulting data as if it were coming from one, single table.<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database view as a design-time<br />
file in the repository. Repository files can be read by applications that you develop. In addition, all repository files<br />
including your view definition can be transported to other <strong>SAP</strong> <strong>HANA</strong> systems, for example, in a delivery unit.<br />
If your application refers to the design-time version of a view from the repository rather than the runtime version<br />
in the catalog, for example, by using the explicit path to the repository file (with suffix), any changes to the<br />
repository version of the file are visible as soon as they are committed to the repository. There is no need to wait<br />
for the repository to activate a runtime version of the view.<br />
To define a transportable view using the design-time view specifications, use the configuration schema illustrated<br />
in the following example:<br />
string schema;<br />
string query;<br />
80<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
ool public(default=true);<br />
optional list depends_on_table;<br />
optional list depends_on_view;<br />
The following example shows the contents of a valid transportable view-definition file for a view called MYVIEW:<br />
schema="TEST_DUMMY";<br />
query="SELECT * FROM \"TEST_DUMMY\".\"com.sap.test.tables::<br />
02_HDB_DEPARTMENT_VIEW\"";<br />
depends_on_view=["com.sap.test.tables::02_HDB_DEPARTMENT_VIEW"];<br />
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<br />
file containing the view definition with the suffix .hdbview, for example, MYVIEW.hdbview in the appropriate<br />
package in the package hierarchy established for your application in the <strong>SAP</strong> <strong>HANA</strong> repository. You can activate<br />
the design-time object at any point in time.<br />
Note: On activation of a repository file, the file suffix, for example, .hdbview, is used to determine which<br />
runtime plugin to call during the activation process. The plug-in reads the repository file selected for<br />
activation, parses the object descriptions in the file, and creates the appropriate runtime objects.<br />
5.8 Creating SQL Views<br />
A view is a virtual table based on the dynamic results returned in response to an SQL statement. <strong>SAP</strong> <strong>HANA</strong><br />
Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) enables you to create a database view as a design-time file in the<br />
repository.<br />
To create a view-definition file in the repository, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. Open the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
3. Open the Project Explorer view.<br />
4. Create the view-definition file.<br />
Browse to the folder in your project workspace where you want to create the new view-definition file and<br />
perform the following tasks:<br />
a) Right-click the folder where you want to save the view-definition file and choose New in the contextsensitive<br />
popup menu.<br />
b) Enter the name of the view-definition file in the File Name box and add the file suffix .hdbview, for<br />
example, MYVIEW.hdbview.<br />
c) Choose Finish to save the new view-definition file in the repository.<br />
5. Define the view.<br />
To edit the view-definition file, in the Project Explorer view double-click the view-definition file you created in<br />
the previous step, for example, MYVIEW.hdbview, and add the view-definition code to the file:<br />
Note: The following code example is provided for illustration purposes only.<br />
schema="TEST_DUMMY";<br />
query="SELECT * FROM \"TEST_DUMMY\".\"com.sap.test.tables::<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 81
02_HDB_DEPARTMENT_VIEW\"";<br />
depends_on_view=["com.sap.test.tables::02_HDB_DEPARTMENT_VIEW"];<br />
6. Save the view-definition file.<br />
7. Commit the changes to the repository.<br />
a) Locate and right-click the new view-definition file in the Project Explorer view.<br />
b) In the context-sensitive pop-up menu, choose Team Commit .<br />
5.9 Data Provisioning Using Table Import<br />
You can import data from comma-separated values (CSV) into the <strong>SAP</strong> <strong>HANA</strong> tables using the <strong>SAP</strong> <strong>HANA</strong><br />
Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) table-import feature.<br />
In <strong>SAP</strong> <strong>HANA</strong> XS, you create a table-import scenario by setting up an import-model file, a import-data file, and one<br />
or more comma-separated value (CSV) files containing the content you want to import into the specified <strong>SAP</strong><br />
<strong>HANA</strong> table. The import-model file links the import operation to one or more target tables. The table definition (for<br />
example, in the form of a .hdbtable file) can either be created separately or be part of the table-import scenario<br />
itself.<br />
To use the <strong>SAP</strong> <strong>HANA</strong> XS table-import feature to import data into an <strong>SAP</strong> <strong>HANA</strong> table, you need to understand the<br />
following table-import concepts:<br />
● Table-Import Model<br />
You define the table-import model in a configuration file that specifies the data fields to import and import<br />
target tables of each data field.<br />
● Table-Import Data<br />
You define the table-import data in a configuration file that specifies how to link the CSV data files to the<br />
respective data field and, in turn, the target tables via the table-import model.<br />
● Table-Import Extension<br />
You define the table-import extension in a configuration file that modifies the relationship to an existing table<br />
import data file.<br />
CSV Data File Constraints<br />
The following constraints apply to the table-import feature in <strong>SAP</strong> <strong>HANA</strong> XS:<br />
● The number of table columns must match the number of CSV columns.<br />
● There must not be any incompatibilities between the data types of the table columns and the data types of the<br />
CSV columns.<br />
● Overlapping data in data files is not supported.<br />
● The target table of the import must not be modified (or appended to) outside of the data-import operation. If<br />
82<br />
the table is used for storage of application data, this data may be lost during any operation to re-import or<br />
update the data.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
5.9.1 Table-Import Model<br />
The table-import model is a configuration file that you use to specify the parameters associated with the list of<br />
comma-separated-value (CSV) files that you want to import. The table-import model also specifies, for each<br />
parameter, into which table the linked-data files are imported, for example, the CSV files linked in the table-import<br />
data file.<br />
You can declare a parameter as optional. If a parameter is optional, it is not necessary to assign a value to this<br />
parameter in the implementing table import data object. To declare a variable as optional in the table-import<br />
model, add the keyword optional before the variable, as illustrated in the example below.<br />
optional listCsvFile csvList;<br />
If you want to add comments to your table-import model, use two back slashes (//) as illustrated in the example<br />
below.<br />
listCsvFile fileList; //this is the csv file list<br />
Example Table-Import Model File<br />
listCsvFile csvFiles;<br />
import csvFiles "TISCHEMA" "TiPackage::TiTable";<br />
5.9.2 Table-Import Data<br />
The table-import data configuration file enables you to specify which table-import model is to be implemented, for<br />
example, TiModel.hdbtim. The file-list parameters created in the table import-model file are assigned to lists of<br />
data-file links, for example, comma-separated values (.csv) files. In the example illustrated below, the .csv is<br />
called TiCsv.csv.<br />
If you want to add comments to your table-import model, use two back slashes (//) as illustrated in the example<br />
below.<br />
implements TiPackage:TiModel.hdbtim; //This is a the import model<br />
You can declare a parameter as final. If a parameter is defined as final, you can prevent modifications of values<br />
assigned to file lists, for example, in a table-import extension. To declare a variable as final in the table-import data<br />
file, add the keyword final before the variable, as illustrated in the example below.<br />
final csvFiles = ["sap.mypackage:data.csv"];<br />
Example Table-Import Data File<br />
implements TiPackage:TiModel.hdbtim; //This is a comment<br />
csvFiles = ["TiPackage:TiCsv.csv"];<br />
csvFilesExt = [<br />
{<br />
file="TiPackage:TiCsv.csv"<br />
},<br />
{<br />
header = false;<br />
file = "sap.xse:csv_config.csv";<br />
keys = [ "Col1" : "b*", "Col1" : "a"];<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 83
}<br />
];<br />
5.9.3 Table-Import Extensions<br />
The table-import feature enables you to modify the initial settings for variables defined in table-import<br />
configuration files by specifying new settings for defined variables in separate extension files.<br />
If both a table-import model and a table-import data file exist, then you can modify initial variable assignments<br />
made in one table-import data file in a subsequent table-import data files (so called extensions) - as long as the<br />
variables are not declared explicitly as final in a previous file. The modification takes place only on the data values<br />
of variables, for example, in a table-import-extension data file, where values can be augmented or be replaced.<br />
The result is a chain of table-import data artifacts. The end result of a successful table import operation is based<br />
on the resulting definition of the file-list parameter as a result of all data files in the chain.<br />
Note: You can only create a linear chain of extensions. It is not permitted to create two table import data<br />
files modifying the same base table import data files.<br />
The following example illustrates a simple table-import model named timodel.hdbtim in the package<br />
TiPackage.<br />
csvFileList csvList;<br />
import csvList "TISCHEMA" "TiPackage::TiTable";<br />
The following example illustrates the contents of a simple table-import data file named tidata.hdbtid, which<br />
implements the table-import model defined in timodel.hdbtim illustrated above.<br />
implements TiPackage:timodel.hdbtim;<br />
csvList = ["TiPackage:mydata.csv"];<br />
The following example illustrates how to extend the definition in the table-import data file tidata.hdbtid<br />
illustrated above.<br />
modifies sap.myPackage:tidata.hdbtid;<br />
csvList = csvList + ["TiPackage:myotherdata.csv"];<br />
After activation of the table-import files, the data from both CSV files (TiPackage:mydata.csv, and<br />
TiPackage:myotherdata.csv) is imported into the target table.<br />
5.9.4 Table-Import Configuration-File Syntax<br />
When you define the details of the table-import operation, you use the following file-list types to enable the<br />
processing of certain data formats:<br />
● csvFileList<br />
Used to specify list of comma-separated values (CSV) file links. The linked CSV files are imported into the<br />
target table specified in the table import model. The import process parses and validates the CSV file format.<br />
● csvFileListExt<br />
84<br />
Similar to (but more flexible than) csvFileList since more settings are possible. You must specify the target<br />
table and the destination file list of CSV files, which is also extendable. For each CSV file it is possible to define<br />
the following additional options:<br />
○ If a header is given or not<br />
○ Which delimiter is use to separate the CSV data<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
○ The key area of the input values<br />
○ If values are optionally enclosed by an given delimiter<br />
Table Import Model Example<br />
The following example shows how to use the file list types csvFileList and csvFileListExt in the table-import<br />
model definition:<br />
listCsvFile csvFiles;<br />
import csvFiles "TISCHEMA" "TiPackage::TiTable";<br />
listCsvFileExt csvFilesExt;<br />
import csvFilesExt "TISCHEMA" "TiPackage::TiTableExt";<br />
Table Import Data Example<br />
The following example shows how to use the file list types csvFileList and csvFileListExt in the table-import<br />
data definition:<br />
implements TiPackage:TiModel.hdbtim;<br />
csvFiles = ["TiPackage:TiCsv.csv"];<br />
csvFilesExt = [<br />
{<br />
file="TiPackage:TiCsv.csv"<br />
},<br />
{<br />
header = false;<br />
file = "sap.xse:csv_config.csv";<br />
keys = [ "Col1" : "b*", "Col1" : "a"];<br />
}<br />
];<br />
5.10 Importing Data Using Table Import<br />
The table-import function imports data from comma-separated values (CSV) files into <strong>SAP</strong> <strong>HANA</strong> tables.<br />
Before you start this task, make sure that the following prerequisites are met:<br />
● An <strong>SAP</strong> <strong>HANA</strong> database instance is available.<br />
● The <strong>SAP</strong> <strong>HANA</strong> database client is installed and configured.<br />
● You have a database user account set up with the roles containing sufficient privileges to perform actions in<br />
the repository, for example, add packages, add objects, and so on.<br />
● The <strong>SAP</strong> <strong>HANA</strong> studio is installed and connected to the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
● You have a development environment including a repository workspace, a package structure for your<br />
application, and a shared project to enable you to synchronize changes to the project files in the local file<br />
system with the repository.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 85
Note: The names used in the following task are for illustration purposes only; replace the names of<br />
schema, tables, files, and so on shown in the following examples with your own names.<br />
1. Create a root package for your table import application.<br />
In <strong>SAP</strong> <strong>HANA</strong> studio, open the <strong>SAP</strong> <strong>HANA</strong> Development perspective and perform the following steps:<br />
a) In the Navigator view, right-click the package in the package hierarchy where you want to create the new<br />
package for your table-import configuration and choose New > Package... .<br />
b) Enter a name for your package, for example TiPackage.<br />
Note: Naming conventions exist for package names, for example, a package name must not start<br />
with either a dot (.) or a hyphen (-) and cannot contain two or more consecutive dots (..). In<br />
addition, the name must not exceed 190 characters.<br />
a) Choose OK to create the new package.<br />
2. Create a set of table-import files.<br />
The following files are required for a table import scenario.<br />
○ The table-import data file, for example, TiData.hdbtid<br />
Links the CSV data files to the data field and thus the target tables via the model<br />
○ A table-import model, for example, TiModel.hdbtim<br />
Defines the data fields and import target tables of each data field<br />
○ A table import package, for example, TiPackage<br />
Contains all the artifacts you need to complete the table-import operation<br />
○ A CSV file, for example, TiCsv.csv<br />
Contains the data to be imported into the <strong>SAP</strong> <strong>HANA</strong> table<br />
○ A table definition, for example, TiTable.hdbtable<br />
Defines the structure of the target import table<br />
○ The schema definition, for example, TISCHEMA.schema<br />
Specifies the name of the schema in which the target import table is created<br />
○ An application-logic, for example, TiConsumerApp.xsjs<br />
Once all files are created, you can import data from a source file, such as a CSV file, into the desired table<br />
during a commit.<br />
3. Using any code editor, open the schema definition (TISCHEMA.schema) file that you just created and enter<br />
the name of the schema you want to apply.<br />
schemaname=TISCHEMA<br />
4. Open the table definition of the target import table (TiTable.hdbtable) file that you just created and enter<br />
86<br />
the following lines of text.<br />
table.schemaName = "TISCHEMA";<br />
table.tableType = COLUMNSTORE;<br />
table.columns =<br />
[<br />
{name = "Surname"; sqlType = VARCHAR; nullable = false; length =<br />
40; comment = "Person's surname";},<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
{name = "Forename"; sqlType = VARCHAR; nullable = false; length =<br />
40; comment = "Person's forename";}<br />
...<br />
];<br />
table.primaryKey.pkcolumns = ["Surname"];<br />
5. Open the CSV file, for example, TiCsv.csv in a text editor and enter some values, for example, the following<br />
lines.<br />
Meyer,Hugo<br />
Schmitt,Michael<br />
Foo,Bar<br />
6. Open the table-import model (TiModel.hdbtim) file that you just created and enter the following lines of<br />
text.<br />
listCsvFile csvFiles;<br />
import csvFiles "TISCHEMA" "TiPackage::TiTable";<br />
7. Open the data definition file (TiData.hdbtid) file that you just created in the same package and enter the<br />
following lines of text.<br />
implements TiPackage:TiModel.hdbtim;<br />
csvFiles = ["TiPackage:TiCsv.csv"];<br />
8. Deploy the table import.<br />
a) Select the package that you created in the first step.<br />
b) Click the alternate mouse button and choose Commit.<br />
c) Click the alternate mouse button and choose Activate.<br />
You have imported data into the <strong>SAP</strong> <strong>HANA</strong> table using the table import feature.<br />
5.11 Using Imported Table Data in <strong>SAP</strong> <strong>HANA</strong><br />
Before you start, ensure that you have deployed a table import.<br />
Note: If you activate the files and then log on to the system using the <strong>SAP</strong> <strong>HANA</strong> studio, you do not have<br />
sufficient privileges to execute a SELECT statement on the table that was created. To be able to execute<br />
the select statement on the table that was created, execute the following statement using the SQL editor<br />
in the <strong>SAP</strong> <strong>HANA</strong> studio:<br />
call<br />
_SYS_REPO.GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT('select','"::"','');<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, write a Select statement to view the imported data.<br />
For example:<br />
SELECT * FROM "TiPackage::TiTable";<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 87
2. Choose Execute.<br />
You can view the contents of the comma-separated values (CSV) file in the <strong>SAP</strong> <strong>HANA</strong> table.<br />
5.12 Using Imported Table Data in an <strong>SAP</strong> <strong>HANA</strong> XS<br />
Application<br />
Before you start, ensure that you have deployed a table import.<br />
Note: If you activate the files and then log on to the system using the <strong>SAP</strong> <strong>HANA</strong> studio, you do not have<br />
sufficient privileges to execute a SELECT statement on the table that was created. You must execute the<br />
following statement using the SQL editor in the <strong>SAP</strong> <strong>HANA</strong> studio:<br />
call<br />
_SYS_REPO.GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT('select','"Ti<br />
Package::TiTable"','');<br />
The example in the note above is for illustration purposes only. In the example shown, TiPackage is the path to<br />
the table-import package in the repository, where package names are separated by a dot (.); TiTable is the name<br />
of the table that is the target for the data-import operation; and is the name of a valid <strong>SAP</strong> <strong>HANA</strong><br />
database user.<br />
To use imported table in an <strong>SAP</strong> <strong>HANA</strong> XS application, perform the following steps:<br />
1. Create an application-descriptor file and place it in your table-import package, for example, TiPackage.<br />
The application-descriptor file has no contents and no name; it only has the file extension .xsapp.<br />
2. Create an application-access file and place it in the package to which you want to grant access, for example, in<br />
same TiPackage package as the application descriptor file you created in the previous step.<br />
The application-access file does not have a name; it only has the file extension .xsaccess.<br />
3. In the application-access (.xsaccess) file, enter the following lines of text:<br />
{<br />
}<br />
"auth_required" : true<br />
4. Create an application-logic file using server-side JavaScript, for example, TiConsumerApp.xsjs and place it<br />
in your table-import package, for example TiPackage.<br />
The application-logic file is the <strong>SAP</strong> <strong>HANA</strong> XS JavaScript application you use to access the data imported into<br />
the table.<br />
5. Enter the following lines of text into your application-logic file, for example, TiConsumerApp.xsjs.<br />
88<br />
Note: The following example is for illustration purposes only. In the example shown,<br />
.TiPackage is the absolute path to the table-import package in the repository and<br />
TiTable is the name of the table that is the target for the data-import operation.<br />
$.response.contentType = "text/plain";<br />
var conn = $.db.getConnection();<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
var pstatement1 = conn.prepareStatement( "SELECT * FROM<br />
\"TiPackage::TiTable\" WHERE \"Surname\"='Meyer");<br />
var result = pstatement1.executeQuery();<br />
if (result)<br />
{<br />
if (result.next())<br />
{<br />
$.response.setBody('The sql statement execution was successful.');<br />
}<br />
else<br />
{<br />
$.response.setBody("No data found");<br />
}<br />
$.response.status = $.net.http.OK;<br />
}<br />
else<br />
{<br />
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;<br />
}<br />
result.close();<br />
pstatement1.close();<br />
conn.close();<br />
6. Select the package that you created in the first step.<br />
7. Click the alternate mouse button and choose Commit.<br />
8. Click the alternate mouse button and choose Activate.<br />
9. Access the <strong>SAP</strong> <strong>HANA</strong> XS application with the following URL http://:<br />
80//.xsjs.<br />
You receive the message, The SQL statement execution was sucessful.<br />
5.13 Extending a Table Import<br />
Extend an existing table import file by creating a new table-import configuration file that you use to specify how to<br />
modify the relation to an existing table-import file.<br />
Before you start, ensure that you have deployed a table import; the following files are required for a table import<br />
extension scenario.<br />
● The table-import data file, for example, TiData.hdbtid<br />
Links the new comma-separated-values CSV data files to the data fields and, in turn, the target tables via the<br />
model<br />
● The table-import extension file, for example, TiDataExtend.hdbtid<br />
Extends the table-import data file TiData.hdbtid<br />
● A table-import model, for example, TiModel.hdbtim<br />
Defines the data fields and import target tables of each data field<br />
● A table import package, for example, TiPackage<br />
Contains all the artifacts you need to complete the table-import operation<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 89
● A CSV file, for example, TiCsv.csv<br />
Contains the data to be imported into the <strong>SAP</strong> <strong>HANA</strong> table<br />
● A second CSV file, for example, TiCsvExtend.csv<br />
Contains the new (extended) data to be imported into the table<br />
● A table definition, for example, TiTable.hdbtable<br />
Defines the structure of the target import table<br />
● The schema definition, for example, TISCHEMA.schema<br />
Specifies the name of the schema in which the target import table is created<br />
● An application-logic, for example, TiConsumerApp.xsjs<br />
1. Open the repository package that contains the table-import data file (for example, TiData.hdbtid) that you<br />
want to extend.<br />
2. Create a CSV file and give the new CSV file a name, for example, TiCsvExtend.csv.<br />
This is the CSV file that contains the new, extended data to be imported into the table. The extended data<br />
either changes or adds to the date specified in the original CSV file TiCsv.csv.<br />
3. Open the new CSV file TiCsvExtend.csv in any code editor and enter the new, extended values you want to<br />
import separated by a comma.<br />
For example, enter the name NewFoo,Bar.<br />
NewFoo,Bar<br />
Note: The value NewFoo in theTiCsvExtend.csv modifies the original Foo value specified in the first<br />
CSV file TiCsv.csv.<br />
4. Create a table-import data-extension file (for example, TiDataExtend.hdbtid) and place the new data-<br />
extension file in the same package (for example, TiPackage) as the other files.<br />
5. Enter the following lines into the data-extension file TiDataExtend.hdbtid.<br />
Note: The following example is for illustration purposes only. In the example shown,<br />
.TiPackage is the absolute path to the table-import package in the repository and<br />
TiData.hdbtid is the name of the data-extension file for the data-import operation.<br />
modifies TiPackage:TiData.hdbtid;<br />
csvFiles = csvFiles + ["TiPackage:TiCsvExtend.csv"];<br />
6. In the <strong>SAP</strong> <strong>HANA</strong> XS application .xsjs, modify the script to query the<br />
90<br />
new value(s) specified in the table-import extension configuration.<br />
In this example, the table-import extension adds the name NewFoo to the data to be imported to <strong>SAP</strong> <strong>HANA</strong>;<br />
you now want to query the value NewFoo.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model
Note: The following example is for illustration purposes only. In the example shown,<br />
TiPackage is the absolute path to the table-import package in the repository and<br />
TiTable is the name of the table that is the target for the data-import operation.<br />
$.response.contentType = "text/plain";<br />
var conn = $.db.getConnection();<br />
var pstatement1 = conn.prepareStatement( "SELECT * FROM<br />
\"TiPackage::TiTable\" WHERE \"Surname\"='NewFoo");<br />
var result = pstatement1.executeQuery();<br />
if (result)<br />
{<br />
if (result.next())<br />
{<br />
$.response.setBody('The sql statement execution was successful.');<br />
}<br />
else<br />
{<br />
$.response.setBody("No data found");<br />
}<br />
$.response.status = $.net.http.OK;<br />
}<br />
else<br />
{<br />
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;<br />
}<br />
result.close();<br />
pstatement1.close();<br />
conn.close();<br />
7. Access the <strong>SAP</strong> <strong>HANA</strong> XS application with the following URL http://:<br />
80//.xsjs.<br />
You receive the message, The SQL statement execution was successful.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Persistence Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 91
6 Setting Up the Analytic Model<br />
Modeling refers to an activity of refining or slicing data in database tables by creating views to depict a business<br />
scenario. The views can be used for reporting and decision-making.<br />
The modeling process involves the simulation of entities, such as CUSTOMER, PRODUCT, and SALES, and<br />
relationships between them. These related entities can be used in analytics applications such as <strong>SAP</strong><br />
BusinessObjects Explorer and Microsoft Office. In <strong>SAP</strong> <strong>HANA</strong>, these views are known as information views.<br />
Information views use various combinations of content data (that is, non-metadata) to model a business use case.<br />
Content data can be classified as follows:<br />
● Attribute: Descriptive data, such as customer ID, city, and country.<br />
● Measure: Quantifiable data, such as revenue, quantity sold and counters.<br />
You can model entities in <strong>SAP</strong> <strong>HANA</strong> using the Modeler perspective, which includes graphical data modeling tools<br />
that allow you to create and edit data models (content models) and stored procedures. With these tools, you can<br />
also create analytic privileges that govern the access to the models, and decision tables to model related business<br />
rules in a tabular format for decision automation.<br />
You can create the following types of information views:<br />
● Attribute Views<br />
● Analytic Views<br />
● Calculation Views<br />
The figure below shows the process flow for modeling in <strong>SAP</strong> <strong>HANA</strong>.<br />
92<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
You can perform the following tasks in the Modeler perspective:<br />
● Import metadata<br />
Create tables by importing the table definitions from the source systems using the Data Services<br />
infrastructure. For more information, see Importing Table Definitions.<br />
● Load data<br />
Note: You can also create tables from scratch using the <strong>SAP</strong> <strong>HANA</strong> Development perspective. For<br />
more information, see Setting Up the Persistence Model.<br />
Load data into the table definitions imported from the source system using the Load Controller, Sybase<br />
Replication Server or <strong>SAP</strong> Landscape Transformation, and from flat files. For more information, see Loading<br />
Data into Tables.<br />
● Create packages<br />
Note: You can also provision data into the table definitions in the <strong>SAP</strong> <strong>HANA</strong> Development perspective.<br />
For more information, seeSetting Up the Persistence Model.<br />
Logically group objects together in a structured way. For more information, see Maintaining Repository<br />
Packages.<br />
● Create information views<br />
Model various slices of the data stored in the <strong>SAP</strong> <strong>HANA</strong> database. Information views are often used for<br />
analytical use cases, such as operational data mart scenarios or multidimensional reporting on revenue,<br />
profitability, and so on. For more information, see Creating Views.<br />
● Create procedures<br />
Create procedures using SQLScript for implementing a complex logic that cannot be achieved using other<br />
objects. For more information, see Developing Procedures.<br />
● Create analytic privileges<br />
Control which data that individual users sharing the same data foundation or view can see. For more<br />
information, see Setting Up Roles and Authorizations.<br />
● Import <strong>SAP</strong> NetWeaver BW objects<br />
Import <strong>SAP</strong> NetWeaver BW objects into <strong>SAP</strong> <strong>HANA</strong>, and expose them as information views. For more<br />
information, seeImporting BW Objects.<br />
● Create decision tables<br />
Create a tabular representation of related rules using conditions and actions. For more information, see<br />
Creating Decision Tables.<br />
● Import and export objects<br />
Import and export the content objects from and to the client and server location. For more information,<br />
seeImplementing Lifecycle Management.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 93
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Studio [page 23]<br />
The <strong>SAP</strong> <strong>HANA</strong> studio is an Eclipse-based development and administration tool for working with <strong>SAP</strong> <strong>HANA</strong>,<br />
including creating projects, creating development objects, and deploying them to <strong>SAP</strong> <strong>HANA</strong>. As a developer,<br />
you may want to also perform some administrative tasks, such as configuring and monitoring the system.<br />
6.1 Setting Up the Modeling Environment<br />
6.1.1 Setting Modeler Preferences<br />
You can set preferences for your Eclipse workspace to set up the default settings that the system uses whenever<br />
you log on.<br />
1. Choose Window Preferences Modeler<br />
Note: You can also set the preferences choosing Quick Launch Manage Preferences<br />
2. Identify the required preference and perform the corresponding substeps from the table below:<br />
94<br />
Requirement Preference Substeps<br />
To specify the structure of content<br />
packages in the navigator panel<br />
To set the preferences for loading data<br />
using flat file<br />
To set the default value for the client<br />
that will be used while previewing<br />
model data<br />
Content Presentation Hierarchical - to view the package<br />
structure in a hierarchical manner<br />
such that, the child folder is inside the<br />
parent folder. Flat - to view all the<br />
packages at the same level for<br />
example, sap, sap.ecc, sap.ecc.ui.<br />
Show Object Type Folders - to group<br />
together similar objects in a package<br />
such as attribute views in the Attribute<br />
View package.<br />
Data From Local File 1. Browse the location to save error<br />
log files for data load using flat<br />
files.<br />
2. Enter the batch size for loading<br />
data. For example, if you specify<br />
2000 and a file has records of<br />
10000 rows the data load will<br />
happen in 5 batches.<br />
3. Enter a decision maker count that<br />
will be used to propose data types<br />
based on the file. For example,<br />
enter 200 if you want the<br />
proposal to be made based on the<br />
200 rows of file data.<br />
Default Model Parameters Select the client from the Default<br />
Client drop-down list.<br />
To enforce various rules on objects Validation Rules Select the required rules to be applied<br />
while performing object validation.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Requirement Preference Substeps<br />
Note: Enforcing validation<br />
rules with severity “Error”<br />
are mandatory.<br />
To determine the numbers of rows to<br />
be displayed in a page<br />
Data Preview Select the maximum rows for data<br />
preview as required.<br />
To specify a location for job log files Logs 1. Expand the Logs node.<br />
To enable logging the repository calls<br />
and specify location for repository log<br />
files<br />
To enable search for the attributes<br />
used in the views<br />
To allow lower case alphabets for<br />
attribute view, analytic view,<br />
calculation view, procedure and<br />
analytic privilege names<br />
2. Select Job Log.<br />
3. Browse the location where you<br />
want to save the job log files.<br />
Logs 1. Expand the Logs node.<br />
2. Select Job Log.<br />
3. Select true from the drop-down<br />
list.<br />
4. Browse the location where you<br />
want to save the repository log<br />
files.<br />
Search Options Select Enable Search Attributes. .<br />
Case Restriction Deselect the Model name in upper<br />
case checkbox.<br />
Note: After changing the preferences make sure you choose Apply and OK.<br />
6.1.2 Configuring the Import Server<br />
In order to load data from external sources to <strong>SAP</strong> <strong>HANA</strong> you need to establish a connection with the server. To<br />
connect you need to provide the details of BusinessObjects Data Services repository and ODBC drivers. Once the<br />
connection is established you can import the tables definition and then load the data into table definitions.<br />
1. In the Quick Launch tab page, choose Configure Import Server.<br />
2. Enter the IP address of the server from which you want to import data.<br />
3. Enter the repository name.<br />
4. Enter the ODBC data source, and choose OK.<br />
6.1.3 Importing Table Definitions<br />
One of the ways to create tables to load source system data into <strong>SAP</strong> <strong>HANA</strong> is to import the table definitions from<br />
the source system.<br />
You have configured the <strong>SAP</strong> <strong>HANA</strong> modeler for importing metadata using the Data Services infrastructure.<br />
Use this procedure to import table definitions (metadata) from a source system to load source system data into<br />
<strong>SAP</strong> <strong>HANA</strong>. You can point to these table definitions for creating various content models such as attribute,<br />
analytic, and calculation views.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 95
Based on your requirements, use one of the following approaches:<br />
● Mass Import: To import all table definitions from a source system. For example, you can use this approach if<br />
this is a first import from the given source system.<br />
● Selective Import: To import only selected table definitions from a source system. For example, you can use<br />
this approach if there are only few table definitions added or modified in the source system after your last<br />
import.<br />
1. If you want to import all table definitions, do the following:<br />
a) In the File menu, choose Import.<br />
b) Expand the <strong>SAP</strong> <strong>HANA</strong> Content node.<br />
c) Choose Mass Import of Metadata, and choose Next.<br />
d) Select the target system where you want to import all the table definitions, and choose Next.<br />
e) In the Connection Details dialog, enter the operating system user name and password of the target<br />
system.<br />
f) Select the required source system, and choose Finish.<br />
Note: If the required system is not available from the dropdown list, you need to contact your<br />
administrator.<br />
2. If you want to import selective table definitions, do the following:<br />
a) In the File menu, choose Import.<br />
b) Expand the <strong>SAP</strong> <strong>HANA</strong> Content node.<br />
c) Choose Selective Import of Metadata, and choose Next.<br />
d) Select the target system where you want to import the table definitions, and choose Next.<br />
e) Select the required source system.<br />
Note: If the required system is not available from the dropdown list, you need to add the new<br />
source system using Manage Connections.<br />
f) In the Type of Objects to Import field, select the required type, and choose Next.<br />
g) Add the required objects (tables or extractors) that you want to import.<br />
Note: If you want to add dependent tables of a selected table, select the required table in the<br />
Target panel, and choose Add Dependent Tables in the context menu.<br />
h) Select the schema into which you want to import the metadata.<br />
i) If you selected object type as extractor, select the package into which you want to place the<br />
corresponding objects.<br />
j) Choose Next, then review and confirm the import by choosing Finish.<br />
If the source object is a table or non V-type extractor, the system creates physical tables and stores them in<br />
the selected schema. However, if the source object is a V-Type extractor, the system creates content models<br />
and stores these models in the selected package, and the underlying physical tables in the schema.<br />
Configuring Data Services for Metadata Import<br />
Use this procedure to enable the <strong>SAP</strong> <strong>HANA</strong> modeler to import table definitions from the source system using the<br />
Data Services infrastructure.<br />
1. Set the Passphrase<br />
96<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
a) Log on to the Central Management Console of <strong>SAP</strong> BusinessObjects Enterprise (BOE).<br />
b) Choose Manage Applications Data Services Application Settings .<br />
c) In the Encryption Passphrase field, enter the passphrase that you have been using for the <strong>SAP</strong> <strong>HANA</strong><br />
studio, and choose Save.<br />
d) Restart the TOMCAT and BOE services.<br />
2. Disable Session Security<br />
a) Log on to the Data Services Management Console.<br />
b) Choose Administrator.<br />
c) In the Navigator panel, choose Web Services.<br />
d) Choose the Web Services Configuration tab page.<br />
e) Select the Import_Repo_Object checkbox to save the connection details.<br />
f) Select Disable Session Security from the dropdown menu, and choose Apply.<br />
3. Creating a Data Source<br />
a) Go to Start Control Panel Administrative Tools .<br />
b) Choose Data Sources (ODBC).<br />
c) Choose the System DSN tab page, and choose Add.<br />
d) Select HDBODBC from the driver list, and choose Finish.<br />
e) Enter a name and description for the data source.<br />
f) Enter server details.<br />
Note: The format in which you need to enter details is . For<br />
example, abc2012.wdf.sap.corp:30115.<br />
g) Enter the required database details in the format, . For example, M4701.<br />
h) Choose Connect.<br />
Managing Source System Connections<br />
Use this procedure to add or manage a source system connection that is required to import table definitions.<br />
6.1.4 Loading Data into Tables<br />
● If you are using the Load Controller or Sybase Replication Server infrastructure, make sure that you have<br />
imported all table definitions into the <strong>SAP</strong> <strong>HANA</strong> database. For more information, see Importing Table<br />
Definitions.<br />
● If you are using the SLT component, the source system(s), target system and the target schema, are<br />
configured by the administrator during the installation.<br />
Use this procedure to load data into your table definitions. Depending on your requirements, you can perform the<br />
following:<br />
● Initial Load - to load all data from a source <strong>SAP</strong> ERP system into the <strong>SAP</strong> <strong>HANA</strong> database by using Load<br />
Controller or <strong>SAP</strong> Landscape Transformation (SLT). This is mostly applicable when you are loading data from<br />
the source for the first time.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 97
● Data Replication - to keep the data of selected tables in the <strong>SAP</strong> <strong>HANA</strong> database up-to date with the source<br />
system tables by using SyBase Replication Server or <strong>SAP</strong> Landscape Transformation (SLT).<br />
1. In the Quick Launch tab page, choose Data Provisioning.<br />
2. If you are using SLT-based replication, choose Source.<br />
3. Choose Load (for initial load) or Replicate (for data replication) as appropriate.<br />
4. Select the required tables to load or replicate data in any of the following ways:<br />
○ Search for the required tables.<br />
1. Select the table from the list, and choose Add.<br />
2. If you want to save the selected list of tables locally for future reference, select the Export selected<br />
tables checkbox, and specify the target location.<br />
○ Load the list of tables from a local file as follows:<br />
1. Choose Load from file.<br />
2. Select the file that contains the required list of tables.<br />
Note: The supported file type is .csv.<br />
5. If you are using the load controller infrastructure, choose Next and enter the operating system user name and<br />
password.<br />
6. Choose Finish.<br />
Suspending and Resuming Data Load<br />
If you are using SLT- based replication, you can choose to stop data replication temporarily for a selected list of<br />
tables, and later resume data load for these.<br />
1. In the Quick Launch tab page, choose Data Provisioning.<br />
2. Select the source system for which you want to suspend or resume data load.<br />
3. Choose Suspend or Resume as required.<br />
4. Select the tables, and choose Add.<br />
5. Choose Finish.<br />
Uploading Data from Flat Files<br />
Use this procedure to upload data from flat files available in a client file system, to <strong>SAP</strong> <strong>HANA</strong> database.<br />
● If the table schema corresponding to the file to be uploaded already exists in the <strong>SAP</strong> <strong>HANA</strong> database, the<br />
new data records are appended to the existing table.<br />
● If the required table for loading the data does not exist in the <strong>SAP</strong> <strong>HANA</strong> database, create a table structure<br />
based on the flat file.<br />
The application suggests the column names and data types for the new tables and allows you to edit them. The<br />
new table always has a 1:1 mapping between the file and table columns. The application does not allow you to<br />
overwrite any columns or change the data type of existing data. The supported file types are .csv, .xls, and .xlsx.<br />
1. In the File menu, choose Import.<br />
2. In the Select an import source section, expand the <strong>SAP</strong> <strong>HANA</strong> content node.<br />
3. Select Data from Local File, and choose Next.<br />
98<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
4. In the Target System section, select the target system to which you want to import the data using the flat file,<br />
and choose Next.<br />
5. In the Define Import Properties page, browse and select the file containing the data you want to load.<br />
6. If you have selected a CSV file, select a delimiter.<br />
Note: A delimiter is used to determine columns and pick the correct data from them. In a csv file, the<br />
accepted delimiters are ',', ';' and ':'.<br />
7. If you have selected an .xls or .xlsx file, select a worksheet.<br />
8. If you want to load the data into a new table, select the New option and perform the following substeps:<br />
a. Choose Next.<br />
b. On the Manage Table Definition and Data Mapping screen, map the source and target columns.<br />
Note:<br />
○ Only 1:1 column mapping is supported. You can also edit the table definition by changing the<br />
data types, renaming columns, adding or deleting the columns, and so on.<br />
○ You can choose to map the source and target columns using the Auto Map option. If you<br />
choose the one to one option, then first column of the source is mapped to the first column at<br />
the target. If you choose the option Map by name, the source and target columns with the<br />
same name are mapped.<br />
9. If you want to append the data to an existing table, select the Existing option and perform the following<br />
substeps:<br />
a. Choose Next.<br />
b. On the Manage Table Definition and Data Mapping screen, map the source and target columns.<br />
10. If you want to provide a constant value for a column at the target, perform the following substeps:<br />
a. Right-click the column.<br />
b. From the context menu, choose Make As Constant.<br />
c. In the Constant dialog box, enter a value, and choose OK.<br />
Note: You can set a column to constant if it is not mapped to a source column.<br />
11. To provide a default value for a column at the target, enter a value in the Default Value column.<br />
12. Choose Finish.<br />
6.1.5 Copying Content Delivered by <strong>SAP</strong><br />
You have the following privileges:<br />
● REPO.READ for the source package.<br />
● REPO.MAINTAIN_NATIVE_PACKAGES and REPO.EDIT_NATIVE_OBJECTS for the root package.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 99
Use this functionality for one of the most common scenarios, that is, to copy the standard content shipped by <strong>SAP</strong><br />
or an <strong>SAP</strong> partner to your local package to meet your modeling and reporting use cases. For example, from<br />
sap.ecc.fin to customer.ecc.fin.<br />
Tip: We recommend you copy the content shipped by <strong>SAP</strong> or an <strong>SAP</strong> partner to your local package to<br />
avoid overwriting your changes during the subsequent import.<br />
You can also use this procedure to copy objects, other than <strong>SAP</strong>-shipped in a package to other packages in the<br />
same system based on your business use case.<br />
Caution: If you copy an object but not its dependent objects (if any), the copied object in the target<br />
package will have references to the dependent objects in the source package.<br />
To copy the objects, you need to map the source root packages to the target root packages. You need to activate<br />
the copied objects in the target package to consume them for reporting purposes.<br />
Restriction: For script-based calculation views and procedures, even if you copy the dependent objects,<br />
you need to change the script manually and adjust the dependent object references.<br />
1. In the Quick Launch tab page, choose Mass Copy.<br />
2. To create a mapping between the source package and the target package, perform the following substeps:<br />
a) Choose Add.<br />
b) Select a source package and a target package, and choose Next.<br />
Tip: If you want to create more package mapping, select the source and target packages as<br />
required.<br />
c) Select the required objects, and choose Add.<br />
3. Choose Next to view the summary.<br />
Tip: You can deselect an object to avoid copying it to the target package.<br />
4. Choose Finish to confirm content copy.<br />
6.1.6 Mapping the Authoring Schema to the Physical Schema<br />
Schema mapping is done when the physical schema in the target system is not the same as the physical schema<br />
in the source system, usually in a transport scenario. The schema mapping is maintained via a mapping table.<br />
You use this procedure to map the authoring schemas to the physical database schemas in the target system to<br />
access and deploy the transported objects.<br />
A physical schema is the schema in which the tables are available. It may differ in the source and target systems.<br />
An authoring schema (logical schema) is the physical database schema in the source system with which the<br />
content objects are created.<br />
Content object definitions are stored in the repository, and contain references to the physical database schemas.<br />
When you copy the content objects to a different system, for example, from an <strong>SAP</strong> system to a customer system,<br />
or between customer systems, the object definition still refers to the physical database schemas at the source. To<br />
resolve this, you use schema mapping.<br />
100<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Remember: Schema mapping only applies to references from repository objects to catalog objects. It is<br />
not intended to be used for repository to repository references.<br />
Restriction: You need to map the references of script-based calculation views and procedures manually,<br />
that is, by changing the script.<br />
You can map several authoring schemas to the same physical schema. For example, content objects delivered by<br />
<strong>SAP</strong> refer to different authoring schemas, whereas in the customer system, all these authoring schemas are<br />
mapped to a single physical schema where the tables are replicated.<br />
Remember: The mapping between authoring and physical schema is stored in the configuration table<br />
“_SYS_BI”.”M_SCHEMA_MAPPING”<br />
Note:<br />
● In a system having no schema mapping, the authoring schema is filled 1:1 from the physical schema<br />
otherwise it would not be possible to change the default schema.<br />
● In a system if authoring schema mapping is found, it is checked that whether the current authoring<br />
schema is mapped to the current physical schema as follows: If yes, nothing is done. If not (including<br />
an empty authoring schema case), then the authoring schema is filled. With the backwards mapped<br />
authoring schema if there is a 1:1 mapping i.e. only one authoring schema was found. With this we<br />
simplify the mapping table in customer systems because even for enhancements the content schema<br />
is kept and no additional mapping must be introduced if the customer transports from development<br />
to production With the physical schema in case no or more than one authoring schemas are found.<br />
This indicates that the customer has changed the schema-dependent parts and that therefore his<br />
physical schema is stored also in the authoring schema.<br />
Example use case: Lets assume we have only <strong>SAP</strong>_ERP -> ERP in the mapping table and an analytic<br />
view having defaultSchema = <strong>SAP</strong>_ERP. Let's assume the customer changes the defaultSchema to<br />
CUS. Since CUS has no mapping the authoringSchema of the defaultSchema is set to CUS as well.<br />
Then the customer changes the defaultSchema back to ERP. A 1:1 mapping for ERP is found<br />
(<strong>SAP</strong>_ERP) and then the authoring schema is set back to <strong>SAP</strong>_ERP.<br />
1. In the Quick Launch tab page, choose Schema Mapping.<br />
2. Choose Add.<br />
3. Enter the authoring schema and physical schema that need to be mapped.<br />
4. Choose OK.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 101
Consider a source system, <strong>SAP</strong>, with an information object, AV1. This refers to the table MARA in the<br />
<strong>SAP</strong>_ERP physical database schema. There is a target system, Customer, with the physical database<br />
schema EMEA.<br />
After you import content, the object AV1 cannot be activated in the Customer system, since it still refers<br />
to <strong>SAP</strong>_ERP schema.<br />
AV1 in the Customer system currently refers to <strong>SAP</strong>_ERP. To be able to activate the object, you need to<br />
modify the mapping of AV1 in the Customer system.<br />
To do this, a mapping is created in the target system Customer between the authoring and physical<br />
schema as follows:<br />
Authoring Schema Physical Schema<br />
<strong>SAP</strong>_ERP EMEA<br />
6.1.7 Generating Time Data<br />
For modeling a business scenario that requires time dimension, you can populate time data in the default time-<br />
related tables present in _SYS_BI schema, for example while creating time attribute views. You can choose to<br />
generate the time data for a given time span based on your requirements such as, calendar type and granularity.<br />
If you model a time attribute view without generating time data, when you use data preview an empty view is<br />
shown. Note that if you populate the data before modeling time attribute views, you can use the Value Help from<br />
the respective time tables.<br />
1. In the Quick Launch tab page, choose Generate Time Data.<br />
2. If your financial year is same as that of the calendar year, that is, January to December, in the Calendar Type<br />
dropdown, select Gregorian.<br />
102<br />
a) Enter the period for which you want to generate time data.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
) Select the required granularity<br />
c) Choose Generate.<br />
Note: If the selected granularity is Week or Month, specify the First day of the week.<br />
System populates the generated time data in M_TIME_DIMENSION_YEAR, M_TIME_DIMENSION_MONTH,<br />
M_TIME_DIMENSION_WEEK, M_TIME_DIMENSION tables in _SYS_BI schema.<br />
3. If your financial year is not same as that of the Calendar Year for example, March to April, , in the Calendar<br />
Type dropdown, select Fiscal.<br />
a) Enter the period for which you want to generate the time data.<br />
b) Select the Variant Schema where tables containing variant data are maintained.<br />
Note: Tables T009 and T009B contains Variants information.<br />
c) Select the required variant that specifies the number of periods along with their start and end dates<br />
according to your use case.<br />
d) Choose Generate.<br />
System populates the generated time data in M_FISCAL_CALENDAR table present in the _SYS_BI schema.<br />
6.2 Creating Views<br />
6.2.1 Attributes and Measures<br />
Attributes and measures form the content data that is used for modeling. While attributes represent the<br />
descriptive data like city and country, measures represent quantifiable data like revenue and quantity sold.<br />
Attributes<br />
Attributes are the individual non-measurable analytical elements.<br />
● Simple Attributes<br />
Simple attributes are individual non-measurable analytical elements that are derived from the data<br />
foundation.<br />
For example, PRODUCT_ID and PRODUCT_NAME are attributes of a PRODUCT subject area.<br />
● Calculated Attributes<br />
Calculated attributes are derived from one or more existing attributes or constants.<br />
For example, deriving the full name of a customer (first and last name), assigning a constant value to an<br />
attribute that can be used for arithmetic calculations.<br />
● Private Attributes<br />
Private attributes used in an analytic view allow you to customize the behavior of an attribute for only that<br />
view.<br />
For example, if an analytic view or a calculation view include an attribute view, it inherits the behavior of the<br />
attributes from the attribute view (set the parameter once and it is replicated in all views consuming it).<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 103
By contrast, if you create an analytic view for one specific use case in which you want a particular attribute to<br />
behave differently than it does in the attribute view to which it belongs, you can define it as a private attribute.<br />
Measures<br />
Measures are simple measurable analytical elements. Measures are derived from analytic and calculation views.<br />
● Simple Measures<br />
A simple measure is a measurable analytical element that is derived from the data foundation.<br />
For example, PROFIT.<br />
● Calculated Measure<br />
Calculated measures are defined based on a combination of data from OLAP cubes, arithmetic operators,<br />
constants, and functions.<br />
For example, calculated measures can be used to calculate the total sales of a product across five regions, or<br />
to assign a constant value to a measure for a calculation.<br />
● Restricted Measure<br />
Restricted measures are used to filter the value based on the user-defined rules for the attribute values.<br />
● Counters<br />
Counters add a new measure to the calculation view definition to count the recurrence of an attribute. For<br />
example, to count how many times Product appears.<br />
Note:<br />
You can choose to hide the attributes and measures that are not required for client consumption. For<br />
example, for a complex calculation that is derived from a series of computations, you can hide the levels of<br />
computations that are not required for reporting purposes.<br />
6.2.2 Attribute Views<br />
Attribute views are used to model an entity based on the relationships between attribute data contained in<br />
multiple source tables.<br />
For example, customer ID is the attribute data that describes measures (that is, who purchased a product).<br />
However, customer ID has much more depth to it when joined with other attribute data that further describes the<br />
customer (customer address, customer relationship, customer status, customer hierarchy, and so on).<br />
You create an attribute view to locate the attribute data and to define the relationships between the various tables<br />
to model how customer attribute data, for example, will be used to address business needs.<br />
You can model the following elements within an attribute view:<br />
● Columns<br />
● Calculated Columns<br />
104<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
● Hierarchies<br />
Note: In the Semantics node, you can classify the columns as attributes and build calculated columns<br />
of attribute type.<br />
Note: For more information about the attributes and hierarchies mentioned above, see sections<br />
Attributes and Measures, and Hierarchies.<br />
You can choose to further fine-tune the behavior of the attributes of an attribute view by setting the properties as<br />
follows:<br />
● Filters to restrict values that are selected when using the attribute view.<br />
● Attributes can be defined as Hidden so that they can be used in processes but are not visible to end users.<br />
● Attributes can be defined as key attributes and used when joining multiple tables.<br />
● The Drill Down Enabled property can be used to indicate if an attribute is available for further drill down when<br />
consumed.<br />
Attribute views can later be joined to tables that contain measures within the definition of an analytic view or a<br />
calculation view to create virtual star schema on the <strong>SAP</strong> <strong>HANA</strong> data.<br />
6.2.3 Creating Attribute Views<br />
Attribute views are used to define joins between tables, and to select a subset (or all) of the table's columns and<br />
rows. The rows selected can also be restricted by filters. One application of attribute views is to join multiple<br />
tables together when using star schemas, to create a single dimension table. The resultant dimension attribute<br />
view can then be joined to a fact table via an analytic view to provide meaning to its data. In this use case, the<br />
attribute view adds more columns and also hierarchies as further analysis criteria to the analytic view. In the star<br />
schema of the analytic view, the attribute view is shown as a single dimension table (although it might join multiple<br />
tables), that can be joined to a fact table. For example, attribute views can be used to join employees to<br />
organizational units which could then be joined to a sales transaction via an analytic view<br />
You have imported T009 and T009B tables for creating attribute view of type Time.<br />
Use this procedure to create a view that is used to model descriptive attribute data (that does not contain<br />
measures) using attributes.<br />
Tip: You need this view for creating a multidimensional view.<br />
1. Set Parameter<br />
1. In the Modeler perspective, expand the Content node of the required system.<br />
2. Expand the package to which you want to save your information object.<br />
3. In the context menu of Attribute Views node, choose New .<br />
4. Enter a name and description for the view.<br />
5. To create data foundation for the view, perform substeps of the required scenario given in the table<br />
below:<br />
Scenario Substeps<br />
Create a view with table<br />
attributes.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
In the Sub Type dropdown list, choose Standard.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 105
Scenario Substeps<br />
Create a view with time<br />
characteristics.<br />
Copy a view from an<br />
existing view – in this case,<br />
you can modify the copied<br />
view.<br />
Derive a view from an<br />
existing view – in this case,<br />
you cannot modify the<br />
derived view that acts as a<br />
reference to the base<br />
attribute view.<br />
6. Choose Finish.<br />
1. In the Sub Type dropdown list, choose Time.<br />
2. Select the required calendar type as follows:<br />
a. If the calendar type is Fiscal, select a variant schema, and a fiscal<br />
variant.<br />
b. If the calendar type is Gregorian, select the granularity for the<br />
data.<br />
3. To use the system-generated time attribute view, select Auto Create.<br />
Note:<br />
The system creates a time attribute view based on the default<br />
time tables, and defines the appropriate columns/attributes<br />
based on the granularity. It also creates the required filters.<br />
Note: The tables used for time attribute creation with calendar<br />
type Gregorian are, M_TIME_DIMENSION, M_TIME_DIMENSION_<br />
YEAR, M_TIME_DIMENSION_ MONTH,<br />
M_TIME_DIMENSION_WEEK and for calendar type Fiscal is<br />
M_FISCAL_CALENDAR. If you want to do a data preview for the<br />
created attribute view, you need to generate time data into the<br />
mentioned tables from the Quick Launch tab page.<br />
1. Choose Copy From.<br />
2. Select the required attribute view.<br />
1. In the Sub Type dropdown, choose Derived.<br />
2. Select the required attribute view.<br />
The attribute view editor opens. The Scenario panel of the editor consist of two nodes - Data Foundation and<br />
Semantics. The Data Foundation node represents the tables used for defining the output structure of the view.<br />
The Semantics node represents the output structure of the view, that is, the dimension. In the Details panel<br />
you define the relationship between data sources and output elements.<br />
2. Define Output Structure<br />
106<br />
a) Add the tables that you want to use in any of the following ways:<br />
○ Drag the required tables present in the Catalog to the Data Foundation node.<br />
○ Select the Data Foundation node in the Scenario panel, and in the context menu of the Details panel,<br />
choose Add.<br />
Note: You can choose to add the same table again in Data Foundation using table aliases in the<br />
editor. For example, in cases where you want to have different cardinalities from the same table.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Restriction: It is not allowed to add column views to the Data Foundation.<br />
b) If you want to query data from more than one table, in the Details panel context menu, choose Create<br />
Join, and enter the required details.<br />
Note: After creating the join, you can edit its properties like join type, cardinality, etc in the<br />
Properties view. You can choose to create Text Join between table fields in order to get languagespecific<br />
data. For example, consider that you have a product table that contains product IDs and<br />
no description about products, and you have a text table for products that has a language-specific<br />
description for each product. You can create a text join between the two tables to get languagespecific<br />
details. In a text join, the right table should be the text table and it is mandatory to specify<br />
the Language Column.<br />
c) Add the table columns to the output structure that is, the Semantics node that you want to use to define<br />
attribute data. You can define the attribute data by doing one of the following:<br />
○ Select the toggle button on the left of the table field.<br />
○ Right-click the table field, and choose Add to Output.<br />
d) If you want to specify a filter condition based on which system must display data for a table field in the<br />
output do the following:<br />
1. Right-click the table field, and choose Apply Filter.<br />
2. Select the required operator, and enter filter values.<br />
All the table fields that you have added to the output are automatically mapped as attributes.<br />
3. Define Key Attributes<br />
a) Select the Semantics node.<br />
b) In the Attributes tab page of the Column panel, select the required attribute and select the Type as Key<br />
Attribute.<br />
Remember: If there is more than one key attribute, all key attributes of the attribute view must<br />
point to the same table in the data foundation. The central table of the attribute view is the one to<br />
which all the key attributes point.<br />
Note: In case of auto-generated time attribute views, the attributes and key attributes are<br />
automatically assigned.<br />
4. Optional Step: Create Calculated Columns<br />
a) In the Output of Data Foundation panel, right-click Calculated Columns.<br />
b) In the context menu, choose New.<br />
c) Enter a name and description (label) for the calculated column.<br />
d) Select a data type for the calculated column.<br />
e) Enter length and scale for the calculated coulmn.<br />
f) In the Expression Editor enter the expression. For example, you can write a formula such as,<br />
if("PRODUCT" = 'ABC', "DISCOUNT" * 0.10, "DISCOUNT"). This means if attribute PRODUCT equals the<br />
string ‘ABC’ then DISCOUNT equals to DISCOUNT multiplied by 0.10 should be returned. Otherwise the<br />
original value of attribute DISCOUNT should be used.<br />
g) Choose OK.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
Note: The expression can also be assembled by dragging and dropping the expression elements<br />
from the menus below the editor window.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 107
5. Optional Step: To filter and view the table data in the modeled view, which is relevant to a specific client as<br />
specified in the table fields, such as, MANDT or CLIENT, at runtime perform the following:<br />
1. Select the Semantics node, in the Properties panel edit the Default Client property.<br />
Note: The default value for the property is the one that is specified as a preference. At runtime, if the<br />
property is set to Dynamic then, the value set for the Session Client property is used to filter table<br />
data. The Session Client property is set while creating a user.<br />
Note: You can choose to create hierarchies in order to define relationships between attributes.<br />
Note:<br />
You can choose to associate an attribute with another attribute, which describes it in detail. For<br />
example, when reporting via Label Mapping (also known as Description Mapping), you can associate<br />
Region_ID with Region_Text.<br />
Before SP05, you could associate an attribute with another attribute in a model. In the runtime<br />
object an .description column is generated and is shown during data preview. Now, from<br />
SP05 onwards the behavior is as follows:<br />
○ For an attribute (CUSTOMER) you can now maintain label mapping by selecting another<br />
attribute (TEXT) from the same model as "Label Column" in the Semantics node. The result is<br />
"TEXT" displaying as the label column in data preview. Note that the CUSTOMER.description<br />
column is not generated and is not shown in data preview anymore.<br />
○ If you have created an object using the old editor (which supported the old style of description<br />
mapping) and try to open it using the new editor you will see a new column<br />
CUSTOMER.description (as an attribute) which is hidden and disabled because this column<br />
cannot be used in other places such as parameter/variable, calculated column, restricted<br />
column and so on. You cannot maintain properties for this attribute for example, description.<br />
CUSTOMER.description displays in the data preview as long as you do not change it in the<br />
editor. You can change its name. After changing the name you can maintain its properties and<br />
use it like other attributes.<br />
6. Activate the view using one of the following options in the toolbar:<br />
○ Save and Activate - to activate the current view and redeploy the affected objects if an active version of<br />
the affected object exists. Otherwise only current view gets activated.<br />
○ Save and Activate All - to activate the current view along with the required and affected objects.<br />
Note: You can also activate the current view by selecting the view in the Navigator panel and choosing<br />
Activate in the context menu.<br />
You can find the activated model in the related package. If you want to modify this model, from the context menu,<br />
choose Open and make the necessary changes.<br />
108<br />
Restriction: The behavior of attribute views with the new editor is as follows:<br />
● When an object (a table of an attribute view) is removed and added again in an attribute view in order<br />
to reflect the recently modified columns with its data type, it reflects the previous state of the columns<br />
alone. For more information, see <strong>SAP</strong> Note 1783668.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Related Links<br />
● When you open an attribute view and there is a missing column in the required object, an error is<br />
shown and the editor does not open. For information regarding the solution of this issue, see <strong>SAP</strong><br />
Note 1788552.<br />
Creating Hierarchies [page 127]<br />
Activating Objects [page 132]<br />
Generating Time Data [page 102]<br />
6.2.4 Analytic Views<br />
Analytic views are used to model data that includes measures.<br />
For example, an operational data mart representing sales order history would include measures for quantity,<br />
price, and so on.<br />
The data foundation of an analytic view can contain multiple tables. However, measures that are selected for<br />
inclusion in an analytic view must originate from only one of these tables (for business requirements that include<br />
measure sourced from multiple source tables, see calculation view ).<br />
Analytic views can be simply a combination of tables that contain both attribute data and measure data. For<br />
example, a report requiring the following:<br />
<br />
Optionally, attribute views can also be included in the analytic view definition. In this way, you can achieve<br />
additional depth of attribute data. The analytic view inherits the definitions of any attribute views that are included<br />
in the definition. For example:<br />
<br />
You can model the following elements within an analytic view:<br />
● Columns<br />
● Calculated Columns<br />
● Restricted Columns<br />
● Variables<br />
● Input parameters<br />
Remember: In the Semantics node, you can classify columns and calculated columns as type<br />
attributes and measures. The attributes you define in an analytic view are Local to that view. However,<br />
attributes coming from attribute views in an analytic view are Shared attributes. For more information<br />
about the attributes and measures mentioned above, see section Attributes and Measures.<br />
Note: For more information about the variables and input parameters mentioned above, see sections<br />
Assigning Variables and Creating Input Parameters.<br />
You can choose to further fine-tune the behavior of the attributes and measures of an analytic view by setting the<br />
properties as follows:<br />
● Filters to restrict values that are selected when using the analytic view.<br />
● Attributes can be defined as Hidden so that they are able to be used in processes but are not viewable to end<br />
users.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 109
● Attributes can be defined as key attribute and used when joining multiple tables.<br />
● The Drill Down Enabled property can be used to indicate if an attribute is available for further drill down when<br />
consumed.<br />
● Aggregation type on measures<br />
● Currency and Unit of Measure parameters (you can set the Measure Type property of a measure, and also in<br />
Calculated Column creation dialog, associate a measure with currency and unit of measure)<br />
6.2.5 Creating Analytic Views<br />
Analytic views are typically defined on a fact table that contains transactional data (as measures). Using analytic<br />
views you can create a selection of measures, add attributes and join attribute views.<br />
Analytic views leverage the computing power of <strong>SAP</strong> <strong>HANA</strong> to calculate aggregate data, e. g. the number of sold<br />
cars per country, or the maximum power consumption per day. They are defined on only one fact table, a table<br />
which contains for example, one row per sold car or one row per power meter reading, or some form of business<br />
transaction records. Fact tables can be joined to allow access to more detailed data using a single analytic view as<br />
long as the facts (measures) come from a single table. Analytic views can be defined in a single table, or in joined<br />
tables.<br />
Analytic views can contain two types of columns, attributes and measures, for which measures are of type simple,<br />
calculated, and restricted. Measures are attributes for which an aggregation must be defined. If analytic views are<br />
used in SQL statements then the measures have to be aggregated e. g. using the SQL functions SUM(), MIN(), or MAX(). Normal columns can be handled as regular attributes.<br />
They do not need to be aggregated.<br />
1. Set Parameters<br />
a) In the Modeler perspective, expand the Content node of the required system.<br />
b) Select the package in which you want to save your information object.<br />
c) From the context menu of the package, choose New Analytic View .<br />
Note: Once you have an analytic view in a package, you can also create another one from the<br />
context menu of the Analytic View node in the respective package.<br />
d) Enter a name and description for the view.<br />
e) If you want to create a view based on the existing one, choose Copy From option, and select the required<br />
view.<br />
f) Choose Finish.<br />
The analytic view editor opens. The Scenario panel of the editor consist of the following three nodes:<br />
○ Data Foundation - represents the tables used for defining the fact table of the view.<br />
○ Logical Join - represents the relationship between the selected table fields (fact table) and attribute views<br />
that is, used to create the star schema.<br />
○ Semantics - represents the output structure of the view.<br />
In the Details panel you define the relationship between data sources and output elements.<br />
2. Define Output Structure<br />
110<br />
a) Add the tables that you want to use in any of the following ways:<br />
○ Drag the required tables present in the Catalog to the Data Foundation node.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
○ Select the Data Foundation node in the Scenario panel, and in the context menu of the Details panel,<br />
choose Add Tables.<br />
Note: You can choose to add the same table again in Data Foundation using table aliases in the<br />
editor. For example, if you want to have different cardinalities from the same table.<br />
Restriction: It is not allowed to add column views to the Data Foundation of an analytic view.<br />
However, you can add column views in a calculation view.<br />
Remember: If there is more than one table, you need to specify one of the tables as the central<br />
table (fact table) from which the measures will be derived. You can specify the central table by<br />
selecting a value in the Central Entity property of the Data Foundation node.<br />
b) If you want to query data from more than one table, in the Details panel context menu, choose Create<br />
Join, and enter the required details.<br />
Tip: After specifying the central table or choosing one of the field as measure, when you save the<br />
view automatic assignment of attributes and measures is done. All the numeric fields from the<br />
central table are assigned as measures and others as attributes. In this case, you will not be able<br />
to join measures with other numeric fields. Also, if you have specified all the attributes and<br />
measures of the view before saving it, automatic assignment of attributes and measures will not<br />
overwrite them.<br />
Note: After creating the join, you can edit its properties such as join type, cardinality, etc in the<br />
Properties view. You can choose to create a Text Join between table fields in order to get language<br />
specific data. For example, consider that you have a product table that contains product IDs but<br />
no product description, and you have a text table for products that has language-specific<br />
description for each product. You can create a text join between the two tables to get languagespecific<br />
details. In a text join, the right table should be the text table and it is mandatory to specify<br />
the Language Column.<br />
c) Add the table columns to the output structure (Semantics node) that you want to use to define the facts<br />
in any of the following ways:<br />
○ Select the toggle button on the left of the table field.<br />
○ Right-click the table field, and choose Add to Output.<br />
d) If you want to specify a filter condition based on which system must display data for a table field in the<br />
output, for example to display revenue for only selected companies based on the filter value, do the<br />
following:<br />
1. Right-click the table field, and choose Apply Filter.<br />
2. Select the required operator, and enter filter values.<br />
The table fields selected above form the fact table.<br />
e) To create a star schema that is, linking the fact table with the descriptive data (attribute views), do the<br />
following:<br />
1. Add the required attribute views in the Logical Join node in any of the following ways:<br />
○ Drag the required attribute views present in the Content node to the Logical Join node.<br />
○ Select the Logical Join node in the Scenario panel, and choose Add button to add the attribute<br />
views.<br />
2. Create joins between the views and fact table.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 111
Note: In the Logical Join, you can create a temporal join between the date field of the fact<br />
table to an interval (to and from) field of the attribute view. The temporal join has to start from<br />
the fact table such that the single column must be in the fact table and, the to and from<br />
columns must be in the table that is directly joined to the fact table. The join type must be a<br />
referential join. The supported data types are timestamp, date, and integer.<br />
Restriction: While creating joins you must ensure that a table does not appear twice in any join path (in<br />
particular a self join is not supported). A join path is the set of joins that links the fact table to other<br />
tables.<br />
While creating joins between analytic view and attribute view the same table cannot be used both in<br />
the join path of analytic view and attribute view. Also, in a join path of analytic view and attribute view,<br />
the table of the attribute view which is linked to the fact table should not have an alias table.<br />
3. Optional Step: Create Calculated Column<br />
a) In the Output of Logical Join panel, right-click Calculated Columns.<br />
b) In the context menu, choose New.<br />
c) Enter a name and description (label) for the calculated column.<br />
d) Select a data type, and enter the length and scale for the calculated column.<br />
e) Select the Column Type to determine whether it is a calculated attribute or a calculated measure.<br />
f) If you select Calculate Before Aggregation, select the aggregation type.<br />
Note: If you select Calculate Before Aggregation, the calculation happens as per the expression<br />
specified and then the results are aggregated as SUM, MIN, MAX or COUNT. If Calculate Before<br />
Aggregation is not selected, the data is not aggregated but it gets calculated as per calculation<br />
expression (formula), and the aggregation is shown as FORMULA. If the aggregation is not set,<br />
then it will be considered as an attribute.<br />
g) In the Expression Editor enter the expression. For example, you can write a formula:<br />
if("PRODUCT" = 'ABC, "DISCOUNT" * 0.10, "DISCOUNT") which is equivalent to, if attribute PRODUCT<br />
equals the string ‘ABC’ then DISCOUNT equals to DISCOUNT multiplied by 0.10 should be returned.<br />
Otherwise the original value of attribute DISCOUNT should be used.<br />
Note: The expression can also be assembled by dragging and dropping the expression elements<br />
from the menus below the editor window.<br />
h) If you want to associate the calculated column with currency and unit of measuring quantity, select the<br />
Advanced tab page and select the required Type.<br />
i) Choose OK.<br />
Remember: Calculated Columns can be created only at the Logical Join level and not at the Data<br />
Foundation level.<br />
Note: The aggregation type for calculated columns is only taken into account, if they are calculated<br />
before aggregation<br />
4. Optional Step: Create Restricted Columns<br />
112<br />
You can create restricted columns if you want to filter the value for an output field based on the user-defined<br />
rules. For example, you can choose to restrict the value for the Revenue column only for Region = APJ, and<br />
Year = 2012.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
a) In the Output panel of the Logical Join, right-click Restricted Columns, and choose New.<br />
b) Enter a name and description for the restricted column.<br />
c) From the Column dropdown list, select the column for which you want to apply a restriction.<br />
Caution: The column for which you apply a restriction must be defined as measure in the<br />
semantics node otherwise the validation will fail.<br />
d) Choose Add Restriction.<br />
e) In the Parameter field, select the column that you want to create a restriction for, then select the operator<br />
and value.<br />
f) Choose OK.<br />
Note: For a restricted column the aggregation type of the base column is applied.<br />
5. Define Attributes and Measures<br />
a) Select the Semantics node.<br />
b) In the Column panel, select the Local tab page, and change the type as attributes and measures.<br />
Note: The Shared tab page shows the attributes of the used attribute views. While generating the<br />
column views, the joined private attribute name is ignored and the shared attribute name is<br />
considered, therefore the joined private attribute is not shown on the Semantics node.<br />
Remember: If the MultiDimensional Reporting property of the analytic view is set to false, the view<br />
will not be available for reporting purposes. If the value is set to true, an additional column<br />
Aggregation is available to specify the aggregation type for measures.<br />
Note:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
You can choose to associate an attribute with another attribute, which describes it in detail. For<br />
example, when reporting via Label Mapping (also known as Description Mapping), you can<br />
associate Region_ID with Region_Text.<br />
Before SP05, you could associate an attribute with another attribute in a model. In the runtime<br />
object an .description column is generated and is shown during data preview. Now,<br />
from SP05 onwards the behavior is as follows:<br />
○ For an attribute (CUSTOMER) you can now maintain label mapping by selecting another<br />
attribute (TEXT) from the same model as "Label Column" in the Semantics node. The result is<br />
"TEXT" displaying as the label column in data preview. Note that the CUSTOMER.description<br />
column is not generated and is not shown in data preview anymore.<br />
○ If you have created an object using the old editor (which supported the old style of description<br />
mapping) and try to open it using the new editor you will see a new column<br />
CUSTOMER.description (as an attribute) which is hidden and disabled because this column<br />
cannot be used in other places such as parameter/variable, calculated column, restricted<br />
column and so on. You cannot maintain properties for this attribute for example, description.<br />
CUSTOMER.description displays in the data preview as long as you do not change it in the<br />
editor. You can change its name. After changing the name you can maintain its properties and<br />
use it like other attributes.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 113
Note: You can change the type of a measure and perform currency conversion by selecting it in<br />
the Local tab page and changing the Measure Type property in the properties panel.<br />
6. Optional Step: You can filter and view the table data in the modeled view for a specific client as specified in the<br />
table fields, such as MANDT or CLIENT, by doing the following:<br />
1. Select the Semantics node, in the Properties panel, edit the Default Client property.<br />
Note: The default value for the property is the one that is specified as a preference. If the property is<br />
set to Dynamic, at runtime the value set for the Session Client property is considered to filter table<br />
data. The Session Client property is set while creating a user.<br />
7. Optional Step: Assign Variable<br />
You assign variables to a field at design time for obtaining data based on the values you provide for the<br />
variable. At runtime, you can provide different values to the variable to view the corresponding set of attribute<br />
data.<br />
a) In the Semantics node Variables/Input Parameter panel, choose the Create Variable option.<br />
b) Enter a name and description for the variable.<br />
c) Select the required attribute from the dropdown list.<br />
Note: At runtime, the value for the variable is fetched from the selected attribute's data.<br />
d) Choose the required Selection Type from the dropdown list.<br />
Note:<br />
○ Single Value - Used to filter and view data based on a single attribute value. For example, to<br />
view the sales of a product where the month is equal to January.<br />
○ Interval - Used to filter and view a specific set of data. For example, to view the expenditure of<br />
a company from March to April.<br />
○ Range - Used to filter and view data based on the conditions that involve operators such as:<br />
○ "="(equal to)<br />
○ ">" (greater than)<br />
○ "=" (greater than or equal to)<br />
○ "
Related Links<br />
Note: If an active version of the affected objects exist, activating the current view redeploys the<br />
affected objects. You can also activate an object from the object context menu in the Navigator panel.<br />
Tip: You can choose to activate the other objects (required or impacted objects) along with the<br />
currenct object using the Save and Activate All option in the toolbar.<br />
Note:<br />
Restriction: The behavior of analytic views with the new editor is as follows:<br />
○ When an object (a table of or an attribute view) is removed and added again in an attribute<br />
view and analytic view editor in order to reflect the recently modified columns with its data<br />
type, it reflects the previous state of the columns . For more information about the<br />
problem and its solution, see <strong>SAP</strong> Note 1783668.<br />
○ When you open an analytic view and there is a missing column in the required object, an<br />
error is shown and the editor does not open. For information regarding the solution of this<br />
issue, see <strong>SAP</strong> Note 1788552.<br />
Using Currency and Unit of Measure [page 130]<br />
Activating Objects [page 132]<br />
Creating Input Parameters [page 125]<br />
6.2.6 Calculation Views<br />
A calculation view is used to define more advanced slices on the data in <strong>SAP</strong> <strong>HANA</strong> database. Calculation views<br />
can be simple and mirror the functionality found in both attribute views and analytic views. However, they are<br />
typically used when the business use case requires advanced logic that is not covered in the previous types of<br />
information views.<br />
For example, calculation views can have layers of calculation logic, can include measures sourced from multiple<br />
source tables, can include advanced SQL logic, and so on. The data foundation of the calculation view can include<br />
any combination of tables, column views, attribute views and analytic views. You can create joins, unions,<br />
projections, and aggregation levels on the sources.<br />
You can model the following elements within a calculation view:<br />
● Attributes<br />
● Measures<br />
● Calculated measures<br />
● Counters<br />
● Hierarchies (created outside of the attribute view)<br />
● Variables<br />
● Input parameters<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
Note: For more information about the attributes, measures, counters, and hierarchies mentioned<br />
above, see sections Attributes and Measures, and Hierarchies.<br />
Note: For more information about the variables and input parameters mentioned above, see sections<br />
AssigningVariables and Creating Input Parameters.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 115
Calculation views can include measures and be used for multi-dimensional reporting or can contain no measures<br />
and used for list-type of reporting. Calculation views can either be created using a graphical editor or using a SQL<br />
editor. These various options provide maximum flexibility for the most complex and comprehensive business<br />
requirements.<br />
6.2.7 Creating Calculation Views<br />
Calculation views are used to provide composites of other views. Essentially they are based on a join or union of<br />
two or more data flows or on invoke of built-in or generic SQL functions.<br />
Calculation views are defined as either graphical views or scripted views but not as SQLScript (for exceptions, see<br />
below) depending on how they are created. They can be used in the same way as analytic views, however, in<br />
contrast to analytic views it is possible to join several fact tables in a calculation view.<br />
Graphical views can be modeled using the graphical modeling features of the <strong>SAP</strong> <strong>HANA</strong> Modeler. Scripted views<br />
are created as sequences of SQL statements.<br />
As mentioned previously calculation views are generally not created using SQLScript. There are however,<br />
exceptions to this rule. SQLScripts with the following properties can be used in calculation views:<br />
- No input parameters<br />
- Always read-only (that is, do not make changes to the database)<br />
- Side-effect free<br />
You can use calculation views to derive values and key performance indicators(KPIs).<br />
Note: The terms "attribute" and "columns" are used interchangeably in this procedure. They may denote a<br />
table column, a particular data field of a table row, or the contents of such a data field. The respective<br />
meaning should be clear from the context.<br />
Procedure<br />
1. In the Modeler perspective, expand the system node from the Navigator pane.<br />
2. Expand the Content node.<br />
3. Right-click the required package.<br />
4. From the context menu, choose New Calculation View .<br />
a. Enter a name and description.<br />
b. Select the required package.<br />
Create a Script-Based Calculation View<br />
1. Choose SQL Script.<br />
2. Select the required schema from the Default Schema dropdown list, for unqualified access in SQL.<br />
Note: If you do not select a default schema, while scripting, you need to provide fully qualified names<br />
of the objects used.<br />
3. Select the required option from the Run With dropdown list, which identifies whose rights are to be considered<br />
116<br />
while executing the calculation scenario.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Note:<br />
Definer's right: If you want system to use the rights of the definer while executing the view or<br />
procedure for any user.<br />
Invoker's right: If you want system to use the rights of the current user while executing the view or<br />
procedure .<br />
4. Choose Finish.<br />
5. Define the Output Structure<br />
a. Choose Define Output Parameter from the Output pane.<br />
b. To add the output parameters with the required data type and length, from the Output pane toolbar,<br />
choose Define Output Parameter button.<br />
c. Choose OK.<br />
6. Define the Function<br />
Note: The order and data types of the output parameters should match the table columns order<br />
and data type which is used in the select query.<br />
a. Define the function using SQL Script commands.<br />
Note:<br />
7. Save and Activate<br />
○ You can create variables, and bind them to attributes for filtering data. The values you provide<br />
for the variables at runtime determine which data records are selected for consumption.<br />
○ You can create input parameters for the calculation view that works as a placeholder in a<br />
query.<br />
○ You can create a hierarchy between attributes of the view.<br />
a. To save the view, choose File Save .<br />
b. From the context menu of the calculation view, choose Activate.<br />
Create a Graphical Calculation View<br />
1. Choose Graphical.<br />
2. Select the required schema from the Schema for Conversion dropdown list.<br />
Note: The schema selected for conversion is used during the currency conversion. It list down all the<br />
schemas which has currency related tables and the same can be changed during design time from the<br />
properties.<br />
3. Choose Next.<br />
4. Follow the instructions in the wizard to select the required tables and content models.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 117
118<br />
Adding Unions/Joins/ Projections/ Aggregation<br />
a. From the Tools Palette, choose the required option as follows:<br />
View Description<br />
Union Used to combine the result set of two or more data<br />
sources. For example, to show the names of all the<br />
employees of a store which has different branches each<br />
maintaining its own employee records table.<br />
Join Used to query data from two or more data sources,<br />
based on a specified condition. For example, to retrieve<br />
the sales of two stores maintaining individual table for<br />
sales based on the customer ID.<br />
Projection Used to filter or create a subset of the required columns<br />
of a table or view for creating the model. For example,<br />
selecting the employee name and sales quantity from a<br />
table consisting of many more columns.<br />
Aggregation Used to summarize data of a group of rows by<br />
calculating values in a column. For example, to retrieve<br />
total sales of a product in a month. The supported<br />
aggregation types are sum, min, and max.<br />
Note:<br />
○ The input for union, join, projection, and aggregation views can consist of data sources, union,<br />
join, projection, or aggregation views.<br />
○ You can have only one source of input for aggregation and projection views.<br />
○ You can choose to create filters on projection and aggregation view attributes.<br />
b. Map the input to the selected option.<br />
Mapping attributes<br />
a. To map attributes in a union view, drag and drop the required columns from Source to Target.<br />
You can also modify the attribute mapping. For more information, see Managing Attribute Mappings<br />
[page 122]<br />
Tip: To create a system generated mapping, choose Auto Map By Name.<br />
b. In case of a join view, join the columns of the source data sources.<br />
Note:<br />
○ The output of a union view is the attributes that you added to the Target.<br />
○ The output of a join view is the joined attributes. However, to add additional attributes to the<br />
view's output, from the context menu, choose Add to Output.<br />
○ To add attributes of projection or aggregation view to its output, choose Add to Output from<br />
the context menu.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Optional Step: Creating Calculated Columns<br />
The output of union, join, or projection view is stored under the Column node in the Output panel.To<br />
perform calculations on these columns, do the following:<br />
1. Right-click the Calculated Columns node.<br />
2. From the context menu, choose New.<br />
a. Enter the name.<br />
b. Select the data type.<br />
c. Enter the length and scale.<br />
d. To perform calculations on the output columns, do the following:<br />
○ If you know the formula, enter the expression to perform the calculation.<br />
○ From the list, select the required elements, operator, and functions.<br />
e. Choose Add.<br />
Optional Step: Applying Filter on Aggregation and Projection View Attributes<br />
1. Right-click the required attribute.<br />
2. From the context menu, choose Apply Filter.<br />
3. Select the required operator.<br />
4. Enter value.<br />
5. Choose OK.<br />
Note: You can edit a filter using filter expressions from the Output pane which provides you<br />
with more conditions that can be used in the filter including AND, OR, and NOT. For example,<br />
to retrieve the sales of a product where (revenue >= 100 AND region = India) OR (revenue<br />
>=50 AND region = Germany).<br />
Note: In order to define pattern-based filters in calculation views, you use the expression<br />
editor accessed by double-clicking the expression icon under the filter node of the Output<br />
panel. If you type<br />
match("ABC",'*abc*')<br />
the equivalent SQL is<br />
.<br />
where “ABC“ like ‘%abc%’<br />
Adding Attributes and Measures to Calculation View Output<br />
a. From the designer panel, choose the Output node.<br />
b. To add an attribute, from the context menu, choose Add as Attribute.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 119
120<br />
c. To add a measure, from the context menu, choose Add as Measure.<br />
Note: You can choose to associate a measure with the currency or unit of measure. To do so,<br />
select the measure and in the Properties panel select Measure Type.<br />
d. If you want to create calculated attributes, perform the following substeps:<br />
a. In the Output pane, right-click Calculated Attributes.<br />
b. From the context menu, choose New.<br />
c. Enter a name and description.<br />
d. On the Key tab, define the formula for the calculated attribute as follows:<br />
a. Select a data type for the calculated attribute from the dropdown list.<br />
b. Enter the length and scale.<br />
c. Select the required attributes, operator, and function.<br />
d. To check the validity of the formula, choose Validate.<br />
e. Choose Add.<br />
e. To add a Description to the calculated attribute, write the formula as above.<br />
e. If you want to create calculated measures, do the following:<br />
a. In the Output pane, right-click Calculated Measures.<br />
b. From the context menu, choose New.<br />
a. Enter a name and description.<br />
b. Select the required Aggregation Type.<br />
c. If you want to hide the measure while previewing data, choose Hidden.<br />
d. Select the required data type.<br />
e. Enter the length and scale.<br />
f. Define the measure by selecting the required measures, operator, and function.<br />
g. Choose Validate.<br />
h. Choose OK.<br />
Note: You can choose to rename the attributes, calculated attributes, measures, and calculated<br />
measures of the view using the Rename button in the Output panel toolbar. However, renaming a<br />
field can impact other objects that reuse the field as the new name is not reflected in the other<br />
objects.<br />
Optional Step: Creating Counters<br />
To obtain the number of distinct values of an attribute, do the following:<br />
1. In the Output pane, right-click Counters.<br />
2. From the context menu, choose New.<br />
3. Choose Add Attribute.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
4. Choose OK.<br />
Activate<br />
Note:<br />
1. If you set the calculation view property Multidimensional Reporting as disabled, you can<br />
create a calculation view without adding any measure to the calculation view output. A<br />
calculation view without any measure works like an attribute view and is not available for<br />
reporting purposes.<br />
2. You can choose to hide the attributes and measures that are not required for client<br />
consumption by assigning value true to the property Hidden in the Properties pane.<br />
3. You can choose to create variables, and bind them to attributes for filtering data. The values<br />
you provide to the variables at runtime determine which data records are selected for<br />
consumption.<br />
4. You can choose to create input parameters for the union, join, projection, aggregation, and<br />
calculation view output. Also, if the calculation view data sources have input parameters, you<br />
can map them to the calculation view input parameters.<br />
5. You can choose to create hierarchy between attributes of the view.<br />
6. You can specify a value for the view's Default Client property to filter the table data that is<br />
relevant to a specific client as specified in the table fields at runtime, such as, MANDT or<br />
CLIENT. The default value for the property is the one that is specified as a preference. If the<br />
property is set to Dynamic, at runtime, the value set for the Session Client property is<br />
considered to filter table data. The Session Client property is set while creating a user.<br />
a. To activate the view select Save and Activate from the toolbar.<br />
Note:<br />
Note: Activating the current view redeploys the impacted objects if an active version of the<br />
impacted objects exist. You can also activate an object from the context menu of the object in<br />
the Navigator panel.<br />
Tip: You can choose to activate the other objects (required or impacted objects) along with<br />
the current object using the Save and Activate All from the toolbar.<br />
Note: For more information about activation, see Activating Objects [page 132].<br />
1. For an active calculation view, you can preview the data of an intermediate node in a calculation view,<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
which helps to debug each level of a complex calculation scenario having join, union, aggregation,<br />
projection, and output nodes. The data you preview for a node is for the active version of the<br />
calculation view. If no active version for the object exists then you need to activate the object first. You<br />
can choose the Data Preview option from the context menu of a node.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 121
Related Links<br />
2. You can choose to generate documentation for the calculation view. For more information, see<br />
Generating Object Documentation [page 144].<br />
Assigning Variables [page 123]<br />
Creating Input Parameters [page 125]<br />
Creating Hierarchies [page 127]<br />
Managing Attribute Mappings [page 122]<br />
Using Currency and Unit of Measure [page 130]<br />
Activating Objects [page 132]<br />
Mapping Input Parameters [page 122]<br />
Mapping Input Parameters<br />
You use this procedure to map the input parameters in the underlying data sources (analytic views and<br />
calculation views) of the calculation view to the calculation view parameters. You can:<br />
● Map many data source parameters to one calculation view input parameter.<br />
● Perform a one on one mapping of the data source parameters to the calculation view parameters.<br />
Procedure<br />
1. In the Output pane, select an input parameter.<br />
2. In the context menu, choose Manage Mappings.<br />
3. In the Map Data Source Parameters dialog, map the data source input parameters with the calculation view<br />
parameters.<br />
Note: You can choose the Auto Map by Name option to automatically create the input parameters<br />
corresponding to the source and perform a 1:1 mapping. You can also select a source input parameter<br />
and use the following context menu options:<br />
○ Create New Map 1:1 - to create the same input parameter for the calculation view as for the<br />
source, and create a 1:1 mapping between them.<br />
○ Map By Name - to map the source input parameter with the calculation view input parameter<br />
having the same name.<br />
○ Remove Mapping - to delete the mapping between the source and calculation view input<br />
parameter.<br />
Managing Attribute Mappings<br />
You use this procedure to map the source attribute to the target attribute if there are a large number of attributes,<br />
or to assign a constant value to the target attribute.<br />
Procedure<br />
1. Right-click the attribute in the target list.<br />
2. From the context menu, choose Manage Mappings.<br />
122<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
a. To map the source to the target column, select the required source from the dropdown list.<br />
b. To assign a default value to the constant column, enter the value in the Constant Value field. For more<br />
information, see Constant Column [page 123].<br />
c. Select the required data type.<br />
d. Enter the length and scale as required.<br />
e. Choose OK.<br />
Constant Column<br />
In a union view, a Constant Column is created if there are any target or output attributes for which there are no<br />
mappings to the source attributes. The default value for the constant column is NULL.<br />
Note: The target attribute is mapped to all the sources.<br />
For example, you have two tables with similar structures, Actual Sales and Planned Sales, corresponding to the<br />
sales of products. You want to see the combined data in a single view, but differentiate between the data from the<br />
two tables for comparison. To do so, you can create a union view between the two tables and have a constant<br />
column indicating constant values like A & P, as shown below:<br />
Actual Sales<br />
Sales Product<br />
5000 A1<br />
2000 B1<br />
Planned Sales<br />
Sales Product<br />
3000 A1<br />
6000 B1<br />
The result of this query can be as follows:<br />
Actual Planned Indicator Sales Product<br />
A 5000 A1<br />
P 3000 A1<br />
A 2000 B1<br />
P 6000 B1<br />
6.2.8 Assigning Variables<br />
You use this procedure to assign variables to a filter at design time for obtaining data based on the values you<br />
provide for the variable. At runtime, you can provide different values to the variable to view the corresponding set<br />
of attribute data. You provide values to the variables either by entering the values manually, or by selecting them<br />
from the Value Help dialog.<br />
Note: You can apply variables to attributes of analytic and calculation views.<br />
The following types of variables are supported:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 123
Type Description<br />
Single Value Use this to filter and view data based on a single attribute<br />
value. For example, to view the sales of a product where the<br />
month is equal to January.<br />
Interval Use this to filter and view a specific set of data. For example,<br />
to view the expenditure of a company from March to April.<br />
Range Use this to filter and view data based on the conditions that<br />
involve operators such as "="(equal to), ">" (greater than),<br />
"=" (greater than or equal to), and "
a. Enter a name and description.<br />
b. Select the required attribute from the dropdown list.<br />
Note: At runtime, the value for the variable is fetched from the selected attribute's data.<br />
c. Choose the required Selection Type from the dropdown list.<br />
d. If you want to specify a default value that is used to filter attribute data, enter the value in the Default<br />
Value field.<br />
e. Choose OK.<br />
Note: You can also choose to create a variable using the Create Variable option from the context menu of<br />
an attribute. In this case, the details of the variable are pre-filled.<br />
2. Assign a Variable to a Filter<br />
1. On the Output panel, right-click the attribute.<br />
2. In the context menu, choose Apply Filter.<br />
3. In the Operator dropdown list, choose Variable.<br />
4. In the Variable dropdown list, choose the required variable.<br />
5. Choose OK.<br />
Note: You can also choose to create a variable and apply a filter using the Create Variable - Apply Filter<br />
option from the context menu of an attribute.<br />
6.2.9 Creating Input Parameters<br />
Use this procedure to allow you to provide input for the parameters within stored procedures, in order to obtain a<br />
desired functionality when the procedure is executed.<br />
In an analytic view you use input parameters as placeholders during currency conversion and formulas like<br />
calculated columns. When used in formulas, the calculation of the formula is based on the input that you provide<br />
at runtime during data preview. Input parameters are not used for filtering attribute data in analytic views that can<br />
be achieved using variables.<br />
In calculation views you can use input parameter during currency conversion, calculated measures, input<br />
parameters of the script node, and to filter data as well.<br />
You can apply input parameters in analytic and calculation views. If a calculation view is created using an analytic<br />
view with input parameters, those input parameters are also available in the calculation view but you cannot edit<br />
them.<br />
The following types of input parameters are supported:<br />
Type Description<br />
Attribute Value/ Column Use this when the value of a parameter comes from an<br />
attribute.<br />
Currency (available in Calculation View only) Use this when the value of a parameter is in a currency<br />
format, for example, to specify the target currency during<br />
currency conversion.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 125
Type Description<br />
Date (available in Calculation View only) Use this when the value of a parameter is in a date format, for<br />
example, to specify the date during currency conversion.<br />
Static List Use this when the value of a parameter comes from a userdefined<br />
list of values.<br />
Derived From Table (available in Analytic View and Graphical<br />
Calculation View)<br />
Use this when the value of a parameter comes from a table<br />
column based on some filter conditions and you do not need<br />
to provide any input at runtime.<br />
Empty Use this when the value of a parameter could be anything<br />
from the selected data type.<br />
Direct Type (available in Analytic View) Use this to specify an input parameter as currency and date<br />
during currency conversion.<br />
In the case of analytic views, all input parameters are mandatory. However, in the case of calculation views, each<br />
type of input parameter can be either mandatory or non-mandatory. For a mandatory input parameter, it is<br />
necessary to provide a value at runtime. However, for a non-mandatory input parameter, if you do not specify a<br />
value at runtime, the data for the column in which the input parameter is used remains blank.<br />
Note: You can check whether an input parameter is mandatory or not from the properties of the input<br />
parameter in the Properties pane.<br />
Procedure<br />
● If you want to create a formula to analyze the annual sales of a product in various regions, you can use<br />
Year and Region as input parameters.<br />
● If you want to preview a sales report with data for various countries in their respective currency for a<br />
Analytic View<br />
particular date for correct currency conversion, you can use Currency and Date as input parameters.<br />
1. In the Output panel of the Data Foundation or Logical Join node, right-click the Input Parameters node.<br />
Note: You can also create input parameters at the Semantics node level, using the Create Input<br />
Parameter option in the Variables/Input Parameters panel.<br />
2. From the context menu, choose New.<br />
126<br />
a. Enter a name and description.<br />
b. Select the type of input parameter from the Parameter Type dropdown list.<br />
Note:<br />
○ For the Column type of input parameter, you need to select the attribute from the dropdown<br />
list. At runtime the value for the input parameter is fetched from the selected attribute's data.<br />
○ For an input parameter of type Derived from Table, you need to select a table and one of it's<br />
column as Return Column whose value is then used as input for the formula calculation. You<br />
can also define conditions to filter the values of Return Column in the Filters panel. For<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
example, to calculate Discount for specific clients, you can create an input parameter based<br />
on Sales table and return column Revenue with filter set on the Client_ID.<br />
○ For Direct Type input parameter, specify the Semantic Type that describes the use parameter<br />
as a currency or date, for example, to specify the target currency during currency conversion.<br />
c. If required, select a data type.<br />
d. Enter length and scale for the input parameter.<br />
e. Choose OK.<br />
Calculation View<br />
1. In the Output panel, right-click the Input Parameters node.<br />
2. From the context menu, choose New.<br />
a. Enter a name and description.<br />
b. Select the type of input parameter from the dropdown list.<br />
Note:<br />
c. Select a data type.<br />
○ For the Attribute Value type of input parameter, you need to select the attribute from the<br />
dropdown list. At runtime the value for the input parameter is fetched from the selected<br />
attribute's data.<br />
○ For an input parameter of type Derived from Table, you need to select a table and one of it's<br />
column as Return Column whose value is then used as input for the formula calculation. You<br />
can also define conditions to filter the values of Return Column in the Filters panel. For<br />
example, to calculate Discount for specific clients, you can create an input parameter based<br />
on Sales table and return column Revenue with filter set on the Client_ID.<br />
d. Enter length and scale for the input parameter.<br />
e. Choose OK.<br />
6.2.10 Creating Hierarchies<br />
You use this procedure to create hierarchies between attributes to enhance analysis by displaying attributes<br />
according to their defined hierarchical relationships. Hierarchies can exist cross-attributes (that is, Country -<br />
State - City) or within the values of a single attribute (that is, employee manager - employee direct report).<br />
You structure and define relationships between attributes in the attribute view and calculation view using the<br />
following hierarchy types:<br />
● Level Hierarchy<br />
A level hierarchy is rigid in nature, and the root and the child nodes can be accessed only in the defined order.<br />
Level hierarchies consist of one or more levels of aggregation. Attributes roll up into the next higher level in a<br />
many-to-one relationship, and members at this higher level roll up into the next higher level, and so on to the<br />
top level.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 127
For example: an address hierarchy comprised of region, country, state, and so on.<br />
● Parent/Child Hierarchy<br />
A parent/child hierarchy is a hierarchy in a standard view that contains a parent attribute. A parent attribute<br />
describes a self-referencing relationship, or self-join, within the main table. Parent-child hierarchies are<br />
constructed from a single parent attribute.<br />
For example: a bill of materials hierarchy (parent and child) or an employee master (employee and manager)<br />
hierarchy.<br />
Procedure<br />
Creating a Level Hierarchy<br />
1. Select the Semantics node.<br />
2. In the Hierarchies panel, choose Create option .<br />
3. Enter a name and description for the hierarchy.<br />
4. In the Hierarchy Type dropdown, select Level Hierarchy.<br />
5. Select the required value in the Aggregate All Nodes.<br />
Note: This option indicates that data is posted on aggregate nodes and should be shown in the user<br />
interface. For example, if you have the members A with value 100, A1 with value 10, and A2 with value<br />
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<br />
for A.<br />
With the value set to true, you will count the posted value 100 for A as well and see a result of 130.<br />
If you are sure that there is no data posted on aggregate nodes you should set the option to false. The<br />
engine will then calculate the hierarchy faster as when the option is set.<br />
Note that this flag is only interpreted by the <strong>SAP</strong> <strong>HANA</strong> MDX engine. In the BW OLAP engine the node<br />
values are always counted.<br />
6. Enter a value for the default member.<br />
7. Select the required option in the With Root Node dropdown.<br />
Note: If a hierarchy doesn't have a root node but needs one for reporting use case, set the option to<br />
true. This will create a root node.<br />
8. Select the required value from the Node Style dropdown list.<br />
128<br />
Note: Node style determines the composition of a unique node ID. The different values for node styles<br />
are as:<br />
○ Level Name - the unique node ID is composed of level name and node name, for example "[Level<br />
2].[B2]".<br />
○ Name Only - the unique node ID is composed of level name, for example "B2".<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
○ Name Path - the unique node ID is composed of the result node name and the names of all<br />
ancestors apart from the (single physical) root node. For example "[A1].[B2]".<br />
9. Add the required attributes from the drop-down list.<br />
Note: You can select attributes from the required table columns in the drop-down list to add to the<br />
view.<br />
10. Select the required Level Type.<br />
11. Choose OK.<br />
Note: The level type is used to specify formatting instructions for the level attributes.<br />
For example, a level of the type LEVEL_TYPE_TIME_MONTHS can indicate that the attributes of the<br />
level should have a text format such as "January", and LEVEL_TYPE_REGULAR indicates that a level<br />
does not require any special formatting.<br />
Creating a Parent/Child Hierarchy<br />
1. Select the Semantics node.<br />
2. In the Hierarchies panel, choose Create option .<br />
3. Enter a name and description for the hierarchy.<br />
4. In the Hierarchy Type dropdown, choose Parent Child Hierarchy.<br />
5. Select the required value in the Aggregate All Nodes.<br />
Note: This option indicates that data is posted on aggregate nodes and should be shown in the user<br />
interface. For example, if you have the members A with value 100, A1 with value 10, and A2 with value<br />
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<br />
for A.<br />
With the value set to true, you will count the posted value 100 for A as well and see a result of 130.<br />
If you are sure that there is no data posted on aggregate nodes you should set the option to false. The<br />
engine will then calculate the hierarchy faster as when the option is set.<br />
Note that this flag is only interpreted by the <strong>SAP</strong> <strong>HANA</strong> MDX engine. In the BW OLAP engine the node<br />
values are always counted.<br />
6. Enter a value for the default member.<br />
7. Select the required option in the With Root Node dropdown.<br />
Note: If a hierarchy doesn't have a root node but needs to have one for reporting use case, set the<br />
option to true. This will create a root node.<br />
8. Select the Parent Node and Child Node from the dropdown list.<br />
9. Choose OK.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 129
Note: The hierarchies belonging to an attribute view are available in an analytic view that reuses the<br />
attribute view, in read-only mode. However, the hierarchies belonging to an attribute view are not available<br />
in a calculation view that reuses the attribute view.<br />
6.2.11 Using Currency and Unit of Measure<br />
Use this procedure to define a measure as an amount or weight in the analytical space and to perform currency<br />
conversion.<br />
To simplify the process of currency conversion, the system provides a list of currencies, and exchange rates<br />
based on the tables imported for currency. Currency conversion is performed based on source currency, target<br />
currency, exchange rate, and date of conversion. You can also select currency from the attribute data used in the<br />
view.<br />
For example, you need to generate a sales report for a region in a particular currency, and you have sales data in<br />
database tables in a different currency. You can create an analytic view by selecting the table column containing<br />
the sales data in this other currency as a measure, and perform currency conversion. Once you activate the view,<br />
you can use it to generate reports.<br />
Note: Currency conversion is enabled for analytic views and base measures of calculation views.<br />
Prerequisites<br />
● You have imported tables T006 and T006A for Unit of Measure.<br />
● You have imported TCURC, TCURF, TCURN, TCURR, TCURT, TCURV, TCURW, and TCURX for currency.<br />
Procedure<br />
1. Select a measure.<br />
2. In the Properties pane, select Measure Type.<br />
3. If you want to associate the measure with a currency, do the following:<br />
130<br />
a. In the Measure Type dropdown list, select the value Amount with Currency.<br />
b. In the Currency Dialog, select the required Type as follows:<br />
Type Purpose<br />
Fixed To select currency from the currency table TCURC.<br />
Attribute To select currency from one of the attributes used in the<br />
view.<br />
c. Select the required value, and choose OK.<br />
d. If you want to convert the value to another currency, choose Enable for Conversion.<br />
a. To select the source currency, choose Currency.<br />
b. Select the target currency.<br />
Note: For currency conversion, in addition to the types Fixed and Attribute, you can select an<br />
Input Parameter to provide target currency at runtime. If you select an input parameter for<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
specifying target currency and deselect Enable for Conversion checkbox, the target currency<br />
field is cleared because input parameters can be used only for currency conversion.<br />
c. To specify exchange rate type, in the Exchange Rate Types dialog, select the Type as follows:<br />
Type Purpose<br />
Fixed To select exchange rate from the currency table<br />
TCURW.<br />
Input Parameter To provide exchange rate input at runtime as input<br />
parameter.<br />
d. To specify the date for currency conversion, in the Conversion Date dialog, select the Type as follows:<br />
Type Purpose<br />
Fixed To select conversion date from the calendar.<br />
Attribute To select conversion date from one of the attributes<br />
used in the view.<br />
Input Parameter To provide conversion date input at runtime as input<br />
parameter.<br />
e. To specify the schema where currency tables are located for conversion, in the Schema for currency<br />
conversion, select the required schema.<br />
f. To specify the client for which the conversion rates to be looked for, in the Client for currency<br />
conversion, select the required option.<br />
e. From the dropdown list, select the required value that is used to populate data if the conversion fails:<br />
Option Result<br />
Fail In data preview, the system displays an error for<br />
conversion failure.<br />
Set to NULL In data preview, the value for the corresponding records<br />
is set to NULL.<br />
Ignore In data preview, you view the unconverted value for the<br />
corresponding records.<br />
4. If you want to associate a measure with a unit of measure other than currency, do the following:<br />
a. Select the value Quantity with Unit of Measure in the Measure Type dropdown list.<br />
b. In the Quantity Units dialog , select the required Type as follows:<br />
Type Purpose<br />
Fixed To select a unit of measure from the unit tables T006<br />
and T006A.<br />
Attribute To select a unit of measure from one of the attributes<br />
used in the view.<br />
c. Select the required value, and choose OK.<br />
5. Choose OK.<br />
Note: You can associate currency or unit of measure with a calculated measure, and perform currency<br />
conversion for a calculated measure by editing it.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 131
6.2.12 Activating Objects<br />
You activate objects available in your workspace to expose the objects for reporting and analysis. Based on your<br />
requirements, you can do the following:<br />
● Activate - Deploys the inactive objects.<br />
● Redeploy - Deploys the active objects in one of the following scenarios:<br />
○ If your runtime object gets corrupted or deleted, and you want to create it again.<br />
○ If an object goes through client-level activation and server-level activation but fails at MDX, and the object<br />
status is still active.<br />
The following activation modes are supported:<br />
● Activate and ignore the inconsistencies in impacted objects - To activate the selected objects even if it results<br />
in inconsistent impacted objects. For example, if you choose to activate an object A that is used by B and C,<br />
and it causes inconsistencies in B and C but you can choose to go ahead with the activation of A. This is the<br />
default activation mode.<br />
● Stop activation in case of inconsistencies in impacted objects - To activate the selected objects only if there<br />
are no inconsistent impacted objects.<br />
Note: Irrespective of the activation mode, if even one of the selected objects fails (either during validation<br />
or during activation), the complete activation job will fail and none of the selected objects will be activated.<br />
Depending on where you invoke the activation, redeployment or cascade activation, the behavior is as follows:<br />
Context Activate Redeploy<br />
Quick Launch tab page A dialog box appears with a preselected<br />
list of all your inactive objects.<br />
Package context menu A dialog box appears with a preselected<br />
list of all your inactive objects.<br />
Content context menu A dialog box appears with a preselected<br />
list of all your inactive objects.<br />
Editor ● If you select Save and Activate,<br />
current object is activated and the<br />
impacted objects are redeployed if<br />
an active version for the impacted<br />
objects exist.<br />
● If you select Save and Activate All, a<br />
dialog box appears with a<br />
preselected list of the selected<br />
object along with all the required<br />
and impacted objects.<br />
Object context menu A dialog box appears with a preselected<br />
list of the selected object along with all<br />
the required objects.<br />
132<br />
Note:<br />
A dialog box appears with a list of active<br />
objects in your workspace.<br />
A dialog box appears with a list of active<br />
objects in your workspace.<br />
Not applicable<br />
Not applicable<br />
A redeployment job is submitted for the<br />
selected object.<br />
● If an object is the only inactive object in the workspace, the activation dialog box is skipped and the<br />
activation job is submitted.<br />
● If an object is inactive and you want to revert back to the active version, from the editor or object<br />
context menu, choose Revert To Active.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
● In the Activate dialog, you can select the Bypass validation checkbox in order to skip validation before<br />
activation to improve the activation time. For example, if you have imported a number of objects and<br />
want to activate them without spending time on validation.<br />
Note: During delivery unit import, full server side activation is enabled, activation of objects after import is<br />
done. In this case all the imported objects are activated (moved to active table), even if there are errors in<br />
activated or impacted objects. But the objects for which activation results in error are considered as<br />
broken or inconsistent objects which means that the current runtime representation of these objects is<br />
not in sync with the active design time version. The broken objects are shown in the Navigator with an ‘x’<br />
along side.<br />
Note: The behavior of activation job is as follows:<br />
● The status (completed, completed with warnings, and completed with errors) of the activation job<br />
indicates whether the activation of the objects is successful or failed.<br />
● In case of failure that is when the status is completed with errors, the process is rolled back. This<br />
means, even if there are individual objects successfully activated, since the activation job is rolled<br />
back, none of the objects are activated.<br />
● Even in case of failure, the job log shows success in the summary part. This is to help the user to<br />
indicate that those objects were successfully activated without any issues. But because the entire job<br />
is a failure, none of the objects are activated and all of them are rolled back.<br />
● When you open the job log, the summary list shows only those objects that are submitted for<br />
activation. It does not list all the affected objects. They are listed only in detail section.<br />
6.3 Creating Decision Tables<br />
You use this procedure to create a decision table to model related business rules in a tabular format for decision<br />
automation. Using decision tables you can manage business rules, data validation, data quality rules without any<br />
IT knowledge on technical languages like, SQL Script, MDX . A data architect or a developer creates the decision<br />
table and activates it. The active version of the decision table can be used in applications.<br />
Procedure<br />
1. Set Parameters<br />
1. In the Modeler perspective, expand Content .<br />
2. In the context menu of the package, choose New Decision Table .<br />
3. In the New Decision Table dialog box, enter a name and description for the decision table.<br />
4. To create data foundation for the decision table, perform substeps of the required scenario given in the table<br />
below:<br />
Scenario Substeps<br />
Create a decision table from scratch. 1. Choose Create New.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
2. Choose Next.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 133
Scenario Substeps<br />
Note: If you launch the New Decision Table<br />
dialog from the Quick Launch tab page,<br />
specify the package where you want to save<br />
the decision table.<br />
3. Add the required tables, table type or an information<br />
view to the Selected list.<br />
4. Choose Finish.<br />
Create a decision table from an existing decision table. 1. Choose Copy From.<br />
Note:<br />
Note: You can choose to add the required<br />
data sources to the decision table later by<br />
dragging them from the Catalog node in the<br />
Navigator panel to the Data Foundation<br />
panel.<br />
Note: If you launch the New Decision Table<br />
dialog from the Quick Launch page, specify<br />
the package where you want to save the<br />
decision table.<br />
2. Select the required decision table.<br />
3. Choose Finish.<br />
○ Only an active version of an information view can be used. Any changes made to the information<br />
view are not reflected in the decision table.<br />
○ You can create a decision table using an analytic view only if it has a calculated attribute.<br />
○ If you create a decision table using an analytic view, the analytic view must have a calculated<br />
attribute.<br />
2. Create Joins<br />
○ If you choose to create a decision table based on a table type or an information view, you cannot<br />
add any other data source. This implies that a decision table can be based on multiple tables or a<br />
table type or an information view.<br />
○ You can add only one table type or information view to the data foundation.<br />
○ You can mark table type columns and information view columns only as conditions.<br />
1. If you want to define a relationship between tables to query data from two or more tables, do the following:<br />
134<br />
a. In the editor pane, from the context menu, choose Create Join.<br />
b. In the Create Join dialog, select the required tables, columns, join type, and cardinality.<br />
c. Choose Create Join.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Note: You can also create a join between table columns by dragging it from one table column to<br />
another table column. The supported join types are inner, left outer and right outer.<br />
3. Add Conditions and Actions<br />
1. In the Data Foundation view, select the required column, and perform substeps of the required scenario given<br />
in the table below:<br />
Scenario Substeps<br />
Include table field in the output structure. From the context menu, choose Add as Attribute.<br />
Note: Attributes contains a subset of columns<br />
that you use to derive conditions and actions.<br />
Add conditions based on which you want to derive actions. 1. In the Output view, select the required attributes .<br />
2. From the context menu, choose Add as Conditions.<br />
Add actions for the selected conditions. 1. In the Output view, select the required attributes .<br />
2. To add condition values, do the following:<br />
2. From the context menu, choose Add as Actions.<br />
a. In the Decision Table view, right-click a condition, and choose Add Conditions Values.<br />
Note: The supported data types for an operator are:<br />
Operator Supported Data Types Syntax<br />
Not Equal To Number & CHAR-based != ABC<br />
In Number & Char-based In ABC;CDA<br />
Not In Number & Char-based Not In A;B;C<br />
Like CHAR-based Like Abc*<br />
Not Like CHAR-based Not Like Abc*<br />
Greater Than<br />
Greater Than or Equals<br />
Less Than<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
Less Than or Equals<br />
Number & CHAR-based >20<br />
>=20<br />
Number & CHAR-based
Operator Supported Data Types Syntax<br />
< 2012-12-12<br />
After Date Dates After 2012-12-12<br />
Or<br />
> 2012-12-12<br />
Between Date Dates Between 2012-12-12 and<br />
b. Enter a value, and choose OK.<br />
Note:<br />
2012-12-25<br />
○ If a database table column is used as condition, you can use the value help dialog to select the<br />
condition values. You can select multiple values at one time. You can edit a condition value by<br />
selecting the condition, and entering a value.<br />
○ You can enter a pattern for the condition values having data type as VARCHAR. The pattern<br />
must be prefixed with the LIKE and NOT LIKE operators. For example, LIKE a*b or NOT LIKE<br />
a?b. If the LIKE or NOT LIKE operator is not present the pattern is treated as a string<br />
3. To set action values, right-click an action cell, and enter value.<br />
4. If you want to write a complex expression as action value, do the following:<br />
a. Right-click the action field.<br />
b. From the context menu, choose Set Dynamic Value.<br />
c. Write the expression for example, PRICE-(PRICE*0.1).<br />
d. To edit a value you need to select that value.<br />
Note: You can use parameters and table columns of the same data type as that of the action in<br />
expressions.<br />
5. To assign a value to a condition or an action based on the table data, choose Open Value Help Dialog, and do<br />
136<br />
the following:<br />
a. In the Value Help for Column dialog, enter the search string, and choose Find.<br />
Note: If you do not provide a value for search and choose Find, all the data corresponding to the<br />
selected column is shown.<br />
b. Select a value, and choose OK.<br />
Remember:<br />
● You can provide an alias name to a condition or an action by editing the value of Alias name property.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
● You can choose to create parameters and use them as conditions or actions. The values you provide<br />
to the parameters at the runtime determine which data records are selected for consumption. For<br />
more information regarding how to use parameters, Using Parameters in a Decision Table [page<br />
139].<br />
● You can export decision table data to an excel sheet using context menu option Export Data to Excel in<br />
the Decision Table view. You can also import decision table data from an excel using context menu<br />
option Import Data from Excel in the Decision Table view.<br />
● You can arrange the condition and action columns of the decision table depending on how you want<br />
them to appear. For more information, see Changing the Layout of a Decision Table [page 139].<br />
6. Optional Step: Validate Decision Table<br />
1. To set the rules that you want to use for validation do the following:<br />
a. Choose Window Preferences .<br />
b. In the Preferences dialog box, expand Modeler Validation Rules .<br />
c. In the Validation Rules view, select Decision Table checkbox to check for all the rules during validation.<br />
d. If you want to check for individual rules, select the required rules.<br />
e. Choose OK.<br />
2. In the decision table editor, choose Validate in the editor toolbar .<br />
Note: In the Job Log section, you can see the validation status and detailed report of the decision table<br />
7. Activate Decision Table<br />
1. Choose File Save .<br />
2. From the context menu of the decision table, choose Activate.<br />
Note: You can choose to save and activate the view from the editor using .<br />
Result: On successful activation, a procedure corresponding to the decision table is created in _SYS_BIC schema.<br />
The name of the procedure is in the format, /. In addition, if a parameter<br />
is used as an action in the decision table, the corresponding table type is created in _SYS_BIC schema. The name<br />
of the table type is in the format, //TT.<br />
Remember: If in a decision table, parameters are used as conditions then corresponding IN parameters<br />
are generated. Also, if the parameters are used as actions then an OUT parameter is generated.<br />
8. Execute Decision Table Procedure<br />
1. To execute the decision table procedure perform the following steps as required:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 137
Data Source Condition Action Script<br />
Physical tables Physical table<br />
column<br />
Physical table<br />
column<br />
Physical tables Parameters Physical table<br />
Physical tables Physical table<br />
column<br />
column<br />
call ""."";<br />
call "".""(,…,);<br />
Parameters call "".""(?);<br />
Physical tables Parameters Parameters call "".""(,…,,?);<br />
View attributes Parameters call "".""(?);<br />
Parameters Parameters call "".""(,…,,?);<br />
Parameters call "".""(?);<br />
Table Type Parameters Parameters call "".""(,…,,?);<br />
Tip: You can view the procedure name using the Open Definition context menu option on the selected<br />
procedure.<br />
Result: On execution of the procedure, the physical table data is updated (if no parameters are used) based on the<br />
data that you enter in the form of condition values and action values.<br />
Remember: If parameters are being used as actions in a decision table, the physical table is not updated.<br />
9. Data Preview<br />
To preview the populated data in the decision table, in the Decision Table editor, from the toolbar, choose Open<br />
Data Preview.<br />
138<br />
Restriction: Data preview is supported only if:<br />
● A decision table is based on physical tables and has at least one parameter as action.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
● A decision table is based on information views and parameter(s) as action.<br />
6.3.1 Changing the Layout of a Decision Table<br />
Use this procedure to change the decision table layout by arranging the condition and action columns. By default,<br />
all the conditions appear as vertical columns in the decision table. You can choose to mark a condition as a<br />
horizontal condition, and view the corresponding values in a row. The evaluation order of the conditions is such<br />
that first the horizontal condition is evaluated and then the vertical ones.<br />
Note: You can only change the layout of a decision table if it has more than one condition. You can select<br />
only one condition as horizontal condition.<br />
Procedure<br />
1. In the context menu of the Decision Table editor, choose Change Layout.<br />
2. If you want to view a condition as a horizontal condition, in the Change Decision Table Layout dialog, select<br />
Table has Horizontal Condition (HC) checkbox.<br />
Note: By default the first condition in the list of conditions is marked as horizontal.<br />
3. In the Conditions and Actions sections, choose options on the right-hand side of the dialog box to arrange the<br />
conditions and actions in the desired sequence.<br />
4. Choose OK.<br />
5. Save the changes.<br />
Note: The available options to arrange the conditions in a sequence are:<br />
○ Move Condition to Top<br />
○ Move Condition Up<br />
○ Move Condition Down<br />
○ Move Condition to Bottom<br />
Note: You can also set a condition as horizontal from the context menu of the condition in the Output view.<br />
You can also arrange the conditions and actions in the desired sequence in the Output view using the<br />
respective buttons.<br />
6.3.2 Using Parameters in a Decision Table<br />
You use this procedure to create a parameter that can be used to simulate a business scenario. You can use<br />
parameters as conditions and actions in the decision table at design time. Parameters used as conditions,<br />
determine the set of physical table rows to be updated based on the condition value that you provide at runtime<br />
during procedure call. Parameters used as actions, simulate the physical table without updating to it.<br />
The following parameter types are supported:<br />
Type Description<br />
Static List Use this when the value of a parameter comes from a userdefined<br />
list of values.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 139
Type Description<br />
Empty Use this when the value of a parameter could be anything of<br />
the selected data type.<br />
Procedure<br />
Consider a sales order physical table with column headers as follows:<br />
ID Name Supplier Model Price Quantity<br />
If you want to evaluate Discount based on the Quantity and Order Amount, you can create two<br />
parameters, Order Amount and Discount. Use Quantity and Order Amount as the condition, and Discount<br />
as the action. The sample decision table could be:<br />
Quantity Order Amount Discount<br />
>5 50000 10<br />
>=10 100000 15<br />
1. Create a Parameter<br />
1. In the Output pane, right-click the Parameters node.<br />
2. From the context menu, choose New and do the following:<br />
a. Enter a name and description.<br />
b. Select the required data type from the dropdown list.<br />
c. Enter the length and scale as required.<br />
d. Choose the required Type from the dropdown list.<br />
e. Choose OK.<br />
Note: If you have selectedStatic List for Type, choose Add in the List of Values section to add<br />
values. You can also provide an alias for the enumeration value.<br />
2. Use Parameter as Condition or Action<br />
1. In the Output pane, expand the Parameters node.<br />
2. Right-click a parameter, choose Add As Conditions/ Add as Actions.<br />
6.4 Managing Object Versions<br />
6.4.1 Switching Ownership of Inactive Objects<br />
Use this procedure to take over the ownership of the inactive version of an object from other users' workspace.<br />
140<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Objects in edit mode in other workspaces are not available for modification. In order to modify such objects you<br />
need to own the inactive object.<br />
The options available for changing the inactive object ownership are as follows:<br />
Option Purpose<br />
Switch Ownership To take over multiple inactive objects from other users.<br />
Inactive objects that do not have an active version are also<br />
available for take over using this option<br />
Take Over To take a single inactive object from another workspace that<br />
you wish to edit using the editor.<br />
Note: Using this functionality you can only own the inactive version of the object. The active version is<br />
owned by the user who created and activated the object.<br />
Prerequisite<br />
You have obtained the Work in Foreign Workspace authorization.<br />
Procedure<br />
1. If you want to own multiple inactive objects from other workspaces, do the following:<br />
a. In the Quick Launch page, choose Switch Ownership.<br />
b. In the Source User field, select the user who owns the inactive objects.<br />
c. Add the required inactive objects to the Selected Models section.<br />
d. Choose OK.<br />
2. If an object opens in read-only mode and you want to edit it, do the following:<br />
a. In the editor toolbar, select Switch Version.<br />
b. Choose Take Over.<br />
Note: You can choose to save the changes made by the other user (previous owner of the inactive<br />
version) to the inactive version of the object.<br />
6.4.2 Toggling Versions of Content Objects<br />
You use this procedure to view the active version of an information object while working with its inactive version<br />
for example, to view the changes made to the active version.<br />
Procedure<br />
1. In the Modeler perspective, expand the Content node of the required system.<br />
2. Select the required object from a package.<br />
3. From the context menu, choose Open.<br />
4. In the editor pane, choose Show Active Version.<br />
5. Compare the inactive and active versions of the object.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 141
6. Choose OK.<br />
6.4.3 Viewing Version History of Content Objects<br />
You use this procedure to view the version details of an information model for tracking purposes.<br />
Procedure<br />
1. In the Modeler perspective, expand the Content node of the required system.<br />
2. Select the required object from a package.<br />
3. From the context menu, choose History.<br />
6.5 Working with Objects<br />
6.5.1 Managing Layout<br />
You use this procedure to adjust the data foundation and logical view layout comprising user interface controls<br />
like, tables and attribute views in a more readable manner. This functionality is supported for attribute views and<br />
analytic views.<br />
The options available are as follows:<br />
Option Purpose Substeps<br />
Auto Arrange Use this option to arrange the user<br />
interface elements automatically.<br />
Show outline Use this option to view an outline of the<br />
elements arranged so that , you do not<br />
have to navigate in the editor using<br />
horizontal and vertical scrollbars.<br />
Highlight related tables Use this option if you want to view only<br />
those tables that are related to a table<br />
selected in the editor.<br />
Display Use this option if you have a table with a<br />
large number of columns in the editor,<br />
and you want to view them in a way that<br />
meets your needs: for example, only the<br />
table name, or only joined columns, or<br />
the expanded form with all the columns.<br />
6.5.2 Filtering Packages and Objects<br />
In the editor tool bar, choose .<br />
In the editor tool bar, choose .<br />
1. In the editor, right-click the<br />
selected table.<br />
2. From the context menu, choose<br />
Highlight related tables.<br />
1. In the editor, right-click the relevant<br />
table.<br />
2. From the context menu, choose<br />
Display.<br />
3. If you want to view only the table<br />
name, choose Collapsed.<br />
4. If you want to view all the columns<br />
of the table, choose Expanded.<br />
5. If you want to view only the joined<br />
columns of the table, choose Joins<br />
only.<br />
You use this procedure to filter the content, and view packages and objects that you want to work with. If you<br />
apply a filter at the package level, all the packages including subpackages that satisfies the search criteria are<br />
142<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
shown. You can apply a filter for packages only on the Content node in the Navigator panel. You can apply a filter<br />
for objects at the package level including subpackages.<br />
Applying Filter for Packages<br />
1. In the Navigator pane, select the Content node.<br />
2. In the context menu, choose Filter Packages....<br />
3. In the Filter Packages dialog, enter the filter text.<br />
4. If you want to search for the exact word written in the filter text, select Match whole word checkbox.<br />
5. Choose OK.<br />
Note: If a filter already exists on the Content node, the new filter will overwrite the existing one. You can<br />
also apply the previous filter on the Content using Apply Filter '' option.<br />
Applying Filter for Objects<br />
1. In the Navigator pane, expand the Content node.<br />
2. In the context menu of a package, choose Filter Objects....<br />
3. In the Filter Objects dialog, enter the filter text.<br />
4. If you want to search for the exact word written in the filter text, select Match whole word checkbox.<br />
5. If you want to apply the filter on the subpackages, choose Apply filter to sub packages checkbox.<br />
○ If you want to apply a filter only if no filter already exists on the selected package or otherwise retain the<br />
existing filter, choose Apply only if no filter already exists.<br />
○ If you want to apply filter even if there is an existing filter, choose Apply to all and overwrite existing.<br />
6. Choose OK.<br />
Note: If a filter already exists on the package, the new filter will overwrite the existing one.<br />
6.5.3 Refactoring Objects<br />
You use this procedure to restructure your content objects in the Navigator without changing their behavior. As<br />
you move the objects, their references are automatically adjusted. Objects available for refactoring are, packages,<br />
attribute views, analytic views, graphical calculation views, and analytic privileges.<br />
The activation state of the objects from source package to target package is maintained as follows:<br />
At Source At Target<br />
Base Object- active<br />
Impacted Object- active<br />
Base Object- inactive<br />
Impacted Object- inactive<br />
Base Object- active<br />
Impacted Object- active<br />
Base Object- inactive<br />
Impacted Object- inactive<br />
Base Object- active Base Object- active<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 143
At Source At Target<br />
Impacted Object- inactive Impacted Object- active<br />
Base Object- inactive<br />
Impacted Object- active<br />
Base Object- inactive<br />
Impacted Object- inactive<br />
Note: An impacted object (also known as affected object) is the one that uses the base object. For<br />
example, an analytic view using an attribute view is called impacted object for that attribute view.<br />
1. Open the Modeler perspective.<br />
2. Expand the Content node.<br />
3. Select the required objects, in the context menu, choose Refactor Move .<br />
4. In the Move dialog, select the target package where you want to move the package/objects, and choose Next.<br />
5. If you want to skip the movement of objects/packages, in the Changes to be performed panel, deselect them.<br />
6. Choose Finish.<br />
6.5.4 Validating Models<br />
You use this procedure to check if there are any errors in an information object and if the object is based on the<br />
rules that you specified as part of preferences. For example, the "Check join: SQL" rule checks that the join is<br />
correctly formed.<br />
For more information about setting preferences, see Setting Preferences for Modeler .<br />
Procedure<br />
1. On the Quick Launch page, choose Validate.<br />
2. From the Available list, select the required models that system must validate.<br />
3. Choose Add.<br />
4. Choose Validate.<br />
6.5.5 Generating Object Documentation<br />
Use this procedure to capture the details of an information model or a package in a single document. This helps<br />
you view the necessary details from the document, instead of referring to multiple tables. The following table<br />
specifies the details that you can view from the document.<br />
Type Description<br />
Attribute View General object properties, attributes, calculated attributes,<br />
data foundation joins, cross references, and where-used<br />
Analytic View General object properties, private attributes, calculated<br />
attributes, attribute views, measures, calculated measures,<br />
restricted measures, variables, input parameters, data<br />
foundation joins, logical view joins, cross references, and<br />
where-used<br />
144<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Type Description<br />
Calculation View General object properties, attributes, calculated attributes,<br />
measures, calculated measures, counters, variables, input<br />
parameters, calculation view SQL script, cross references,<br />
and where-used<br />
Package Sub-packages, general package properties, and list of<br />
content objects<br />
Procedure<br />
1. From the Quick Launch page, choose Auto Documentation.<br />
2. In the Select Content Type field, select one of the following options as required:<br />
Option Description<br />
Model Details To generate documentation for models such as attribute,<br />
analytic, and calculation views.<br />
Model List To generate documentation for packages.<br />
3. Add the required objects to the Target list.<br />
4. Browse the location where you want to save the file.<br />
5. Choose Finish.<br />
6.5.6 Enabling Multilanguage Support for Objects<br />
You use this procedure to enable translation of text pertaining to objects and their elements that did not have<br />
multilanguage support.<br />
For example, you can enable multilanguage support for models along with their elements like attributes and<br />
measures in different languages.<br />
Procedure<br />
1. From the Quick Launch tab page, choose Migrate.<br />
2. Select the required objects.<br />
3. Choose Add.<br />
4. Choose OK.<br />
Result<br />
Object texts along with the corresponding elements are flagged for translation. These objects can be viewed in<br />
multiple languages provided that the object texts are translated.<br />
6.5.7 Checking Model References<br />
You use this procedure to identify whether an information model is referenced by any other information model(s).<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 145
Procedure<br />
1. In the Modeler perspective, expand the system node in the Navigator pane.<br />
2. Expand the Content node.<br />
3. Expand the required package node.<br />
4. Select the required object.<br />
5. From the context menu, choose Where Used.<br />
6.5.8 Viewing the Job Log<br />
The job log displays information related to requests entered for a job. A job log consists of two tab pages as<br />
follows:<br />
● Current: Lists all waiting, running, and last five jobs.<br />
● History: Lists all the jobs.<br />
Note: You can terminate the job only if it is in the waiting state.<br />
You can perform the following operations using the job log:<br />
● Open Job Details: Use this to view the job summary in the current tab page.<br />
● Open Job Log File: Use this to view the information pertaining to a job in detail using the internal<br />
browser.<br />
● Clear Log Viewer: Use this to delete all the job from the current tab page.<br />
● Export Log File: Use this to export the log file to a target location other than the default location for<br />
further reference.<br />
● Delete Job: Use this to delete single job from the current tab page.<br />
6.5.9 Maintaining Search Attributes<br />
You use this procedure to enable an attribute search for an attribute used in a view. Various properties related to<br />
attribute search are as follows:<br />
● <strong>Free</strong>style Search: Set to True if you want to enable the freestyle search for an attribute. You can exclude<br />
attributes from freestyle search by setting the property to False.<br />
● Weights for Ranking: To influence the relevancy of items in the search results list, you can vary the weighting<br />
of the attribute. You can assign a higher or lower weighting (range 0.0 to 1.0). The higher the weighting of the<br />
attribute, the more influence it has in the calculation of the relevance of an item. Items with a higher relevance<br />
are located higher up the search results list. Default value: 0.5.<br />
Note: To use this setting the property <strong>Free</strong>style Search must be set to True.<br />
● Fuzziness Threshold: This parameter is reserved for the future usage of the fault-tolerant search..<br />
Note: It is recommended to use the default values for ranking and fuzziness at the beginning. You can finetune<br />
the search settings based on the experience gained using the search. You can also fine-tune the<br />
search using feedback collected from your users.<br />
6.5.10 Previewing Data of Content Objects<br />
You use this procedure to preview the content of content models for analysis purposes.<br />
1. In the Modeler perspective, expand the Content node of the required system.<br />
2. Select the object from a package for which you want to view the content.<br />
146<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
3. From the context menu, choose Data Preview.<br />
The system displays the content in different formats as shown in the table below.<br />
Tab Page Displays…<br />
Raw Data All attributes along with data in a table format.<br />
Distinct values All attributes along with data in a graphical format.<br />
Analysis All attributes and measures in a graphical format.<br />
Tip: If there are inconsistencies in runtime information (that is, calculation views in catalog or in tables<br />
related to runtime) of a view, you might get invalidated view error. In such cases, you need to<br />
redeploy the view in order to correct the inconsistencies with runtime information.<br />
4. Navigate to the required tab page and view the content.<br />
6.5.11 Functions used in Expressions<br />
This topic covers the functions that you can use while creating expressions like, calculated attributes and<br />
calculated measures.<br />
Conversion Functions<br />
Function Syntax Purpose Example<br />
int int int(arg) convert arg to int type int(2)<br />
float float float(arg) convert arg to float type float(3.0)<br />
double double double (arg) convert arg to double type double(3)<br />
sdfloat sdfloat sdfloat (arg) convert arg to sdfloat type<br />
decfloat decfloat decfloat (arg) convert arg to decfloat type<br />
fixed fixed fixed (arg, int, int) arg2 and arg3 are the<br />
intDigits and fractdigits<br />
parameters, respectively.<br />
Convert arg to a fixed type of<br />
either 8, 12, or 16 byte length,<br />
depending on intDigits and<br />
fractDigits<br />
string string string (arg) convert arg to string type<br />
raw raw raw (arg) convert arg to raw type<br />
date date date(stringarg)<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
date date(fixedarg)<br />
date date(int, int)<br />
date date(int, int, int)<br />
date date(int, int, int, int)<br />
convert arg to date type. The<br />
first version parses a string in<br />
the format "yyyy-mm-dd<br />
hh:mi:ss" where trailing<br />
components except for the<br />
year may be omitted. The<br />
version with one fixed<br />
number arg strips digits<br />
fixed(3.2, 8, 2) + fixed(2.3, 8,<br />
3)<br />
date(2009) -> date('2009')<br />
date(2009, 1, 2) -><br />
date('2009-01-02')<br />
date(fixed(20000203135026<br />
.1234567, 10, 4)) -><br />
date('2000-02-03 13:50:26')<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 147
Function Syntax Purpose Example<br />
date date(int, int, int, int, int)<br />
date date(int, int, int, int, int,<br />
int)<br />
longdate longdate longdate(stringarg)<br />
longdate longdate(fixedarg)<br />
longdate longdate(int, int, int)<br />
longdate longdate(int, int, int,<br />
int, int)<br />
longdate longdate(int, int, int,<br />
int, int, int)<br />
longdate longdate(int, int, int,<br />
int, int, int, int)<br />
time time time(stringarg)<br />
String Functions<br />
time time(fixedarg)<br />
time time(int, int)<br />
time time(int, int, int)<br />
behind the comma and tries<br />
to make a date from the rest.<br />
The other versions accept the<br />
individual components to be<br />
set.<br />
convert arg to longdate type,<br />
similar to date function<br />
above.<br />
convert arg to time type,<br />
similar to date function above<br />
Function Syntax Purpose<br />
longdate(fixed(2000020313<br />
5026.1234567, 10, 5)) -><br />
longdate('2000-02-03<br />
13:50:26.1234500')<br />
longdate(2011, 3, 16, 9, 48,<br />
12, 1234567) -><br />
longdate('2011-03-16<br />
09:48:12.1234567')<br />
strlen int strlen(string) returns the length of a string in bytes, as<br />
an integer number.<br />
midstr string midstr(string, int, int) returns a part of the string starting at<br />
arg2, arg3 bytes long.<br />
arg2 is counted from 1 (not 0)<br />
leftstr string leftstr(string, int) returns arg2 bytes from the left of the<br />
arg1. If arg1 is shorter<br />
than the value of arg2, the complete<br />
string will be returned.<br />
rightstr string rightstr(string, int) returns arg2 bytes from the right of the<br />
arg1. If arg1 is shorter<br />
than the value of arg2, the complete<br />
string will be returned.<br />
instr int instr(string, string) returns the position of the first<br />
occurrence of the second string<br />
148<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
within the first string (>= 1) or 0, if the<br />
second string is not<br />
contained in the first.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Function Syntax Purpose<br />
hextoraw string hextoraw(string) convert a hexadecimal representation of<br />
bytes to a string of<br />
bytes. The hexadecimal string may<br />
contain 0-9, upper or lowercase a-f and<br />
no spaces between the two digits of a<br />
byte; spaces between bytes are allowed.<br />
rawtohex string rawtohex(string) convert a string of bytes to its<br />
hexadecimal representation.<br />
ltrim string ltrim(string)<br />
string ltrim(string, string)<br />
rtrim string rtrim(string)<br />
string rtrim(string, string)<br />
trim string trim(string)<br />
string trim(string, string)<br />
lpad string lpad(string, int)<br />
string lpad(string, int, string)<br />
rpad string rpad(string, int)<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
string rpad(string, int, string)<br />
The output will contain only 0-9 and<br />
(upper case) A-F, no spaces and is twice<br />
as many bytes as the original string.<br />
removes a whitespace prefix from a<br />
string. The Whitespace characters may<br />
be specified in an optional argument.<br />
This functions operates on raw bytes of<br />
the UTF8-string and has no knowledge<br />
of multi byte codes (you may not<br />
specify multi byte whitespace<br />
characters).<br />
removes trailing whitespace from a<br />
string. The Whitespace characters may<br />
be specified in an optional argument.<br />
This functions operates on raw bytes of<br />
the UTF8-string and has no knowledge<br />
of multi byte codes (you may not<br />
specify multi byte whitespace<br />
characters).<br />
removes whitespace from the beginning<br />
and end of a string.<br />
add whitespace to the left of a string. A<br />
second string argument specifies the<br />
whitespace which will be added<br />
repeatedly until the string has reached<br />
the intended length. If no second string<br />
argument is specified, chr(32) (' ') will<br />
be added. This function operated on<br />
UTF-8 bytes and has no knowledge of<br />
unicode characters (neither for the<br />
whitespace string nor for length<br />
computation).<br />
add whitespace to the end of a string. A<br />
second string argument specifies the<br />
whitespace which will be added<br />
repeatedly until the string has reached<br />
the intended length. If no second string<br />
argument is specified, chr(32) (' ') will<br />
be added. This function operated on<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 149
Function Syntax Purpose<br />
UTF-8 bytes and has no knowledge of<br />
unicode characters (neither for the<br />
whitespace string nor for length<br />
computation).<br />
replace string replace(string, string, string) replace every occurrence of arg2 in arg1<br />
with arg3 and return the resulting string<br />
Mathematical Functions<br />
Function Syntax Purpose Example<br />
sign int sign(double)<br />
int sign(time)<br />
int sign(date)<br />
abs double abs(double)<br />
round<br />
.<br />
rounddown<br />
Date Functions<br />
decfloat abs(decfloat)<br />
decfloat abs(decfloat)<br />
time abs(time)<br />
Sign returns -1, 0 or 1<br />
depending on the sign of its<br />
argument. Sign is<br />
implemented for all numeric<br />
types, date and time.<br />
Abs returns arg, if arg is<br />
positive or zero, -arg else.<br />
Abs is implemented for all<br />
numeric types and time.<br />
double round(double, int) round does rounding of<br />
absolute values toward zer<br />
while the sign is retained<br />
double rounddown(double,<br />
int)<br />
rounddown rounds toward<br />
negative infinity making<br />
rounddown(-1.1, 0) = -2<br />
Function Syntax Purpose<br />
round(123.456, 0) = 123<br />
round(123.456, 1) = 123.5<br />
round(-123.456, 1) = -123.5<br />
round(123.456, -1) = 120<br />
rounddown(123.456, -1) =<br />
120<br />
rounddown(-123.456, -1) =<br />
-130<br />
utctolocal utctolocal(datearg, timezonearg) interprets datearg (a date, without<br />
timezone) as utc and convert it to the<br />
timezone named by timezonearg (a<br />
string)<br />
localtoutc localtoutc(datearg, timezonearg) converts the local datetime datearg to<br />
the timezone specified by the string<br />
timezonearg, return as a date<br />
weekday weekday(date) returns the weekday as an integer in the<br />
range 0..6, 0 is monday.<br />
now now() returns the current date and time<br />
(localtime of the server timezone) as<br />
date<br />
150<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
Function Syntax Purpose<br />
daysbetween daysbetween(date1, date2)<br />
daysbetween(daydate1, daydate2)<br />
daysbetween(seconddate1,<br />
seconddate2)<br />
daysbetween(longdate1, longdate2)<br />
secondsbetween secondsbetween(seconddate1,<br />
seconddate2)<br />
secondsbetween(longdate1, longdate2)<br />
returns the number of days (integer)<br />
between date1 and date2. The first<br />
version is an alternative to date2 - date1.<br />
Instead of rounding or checking for<br />
exactly 24 hours distance, this will<br />
truncate both date values today<br />
precision and subtract the resulting day<br />
numbers, meaning that if arg2 is not the<br />
calendar day following arg1,<br />
daysbetween will return 1 regardless of<br />
the time components of arg1 and arg2.<br />
returns the number of seconds the first<br />
to the second arg, as a fixed point<br />
number. The returned value is positive if<br />
the first argument is less than the<br />
second. The return values are fixed18.0<br />
in both cases (note that it may prove<br />
more useful to use fixed11.7 in case of<br />
longdate arguments).<br />
component component(date, int) the int argument may be int the range<br />
1..6, the values mean year, day, month,<br />
hour, minute, second, respectively. If a<br />
component is not set in the date, the<br />
component function will return a default<br />
value, 1 for the month or the day, 0 for<br />
other components. The component<br />
function may also be applied to<br />
longdate and time types.<br />
addseconds addseconds(date, int)<br />
addseconds(seconddate, decfloat)<br />
addseconds(longdate, decfloat)<br />
adddays adddays(date, int)<br />
Misc Functions<br />
adddays(daydate, int)<br />
adddays(seconddate, int)<br />
adddays(longdate, int)<br />
Return a date plus a number of seconds.<br />
Fractional seconds will also be used in<br />
case of longdate. Null handling is (in<br />
opposition to the default done with<br />
adds) to return null if any argument is<br />
null.<br />
Return a date plus a number of days.<br />
Null handling is (in opposition to the<br />
default done with adds) to return null if<br />
any argument is null.<br />
Function Syntax Purpose Example<br />
if if(intarg, arg2, arg3) return arg2 if intarg is<br />
considered true (not equal to<br />
zero), else return arg3.<br />
Currently, no shortcut<br />
evaluation is implemented,<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
if("NETWR"
Function Syntax Purpose Example<br />
meaning that both arg2 and<br />
arg3 are evaluated in any<br />
case. This means you cannot<br />
use if to avoid a divide by zero<br />
error which has the side<br />
effect of terminating<br />
expression evaluation when it<br />
occurs.<br />
in in(arg1, ...) return 1 (= true) if arg1 is<br />
equal to any of the remaining<br />
args, return 0 else<br />
case<br />
case(arg1, default) case(arg1,<br />
cmp1, value1, cmp2,<br />
value2, ..., default)<br />
return value1 if arg1 == cmp1,<br />
value2 if arg1 == cmp2 etc,<br />
default if there no match<br />
isnull isnull(arg1) return 1 (= true), if arg1 is set<br />
to null and null checking is on<br />
during Evaluator run<br />
(EVALUATOR_MAY_RETURN<br />
_NULL)<br />
6.5.12 Searching Tables, Models and Column Views<br />
case("CATEGORY", 'A', 'LV',<br />
'B', 'MV', 'HV')<br />
You use this feature to search for tables, models and column views in a system. You can search these objects in<br />
any system from the list of systems added in the Navigator panel that has all services started, and is up and<br />
running.<br />
In the search results, for a matching object you can perform the following actions:<br />
● Tables - you can open the table definition and add the table in the analytic and attribute view editor.<br />
Note: You can add a table only if the editor is open otherwise it results in error.<br />
● Models - you can open the models in the editor and in case of attribute view, you can add it in the view editor<br />
of an analytic view.<br />
Note: You can add a model only if the editor is open otherwise it results in error.<br />
● Column Views - you can only open and view the definition.<br />
1. Enter the object that you want to search in the Modeler toolbar search field.<br />
2. Select the system in which you want to search the object from the dropdown option next to the Search<br />
button.<br />
3. To execute the search, choose Search.<br />
The matching objects are listed in the expanded results pane with three tab pages, Tables, Models, and<br />
Column Views. You can select each to view the matching objects and corresponding actions that you can<br />
perform on them, for example, Open and Add.<br />
152<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
6.5.13 Setting Keyboard Shortcuts<br />
You use this procedure to enable the keyboard shortcuts for Modeler actions like, activate, validate, and so on.<br />
The list of supported commands with the default keyboard shortcuts is as follows:<br />
Command Binding When Category<br />
Activate Ctrl+Shift+A Navigator Modeler Keys<br />
Activate Ctrl+Shift+A In Windows Modeler Keys<br />
Add Table/Model Ctrl+Shift+= In Windows Modeler Keys<br />
Auto Arrange Ctrl+L In Windows Modeler Keys<br />
Data Preview Alt+Shift+P Navigator Modeler Keys<br />
Data Preview Alt+Shift+P In Windows Modeler Keys<br />
Display XML Alt+D In Windows Modeler Keys<br />
Find Ctrl+F Navigator Modeler Navigator<br />
Fit to Window Ctrl+0 In Windows Modeler Keys<br />
Move Element in Output<br />
Pane (Direction: Down)<br />
Move Element in Output<br />
Pane (Direction: Up)<br />
Ctrl+] In Windows Modeler Keys<br />
Ctrl+[ In Windows Modeler Keys<br />
Open Ctrl+O Navigator Modeler Keys<br />
Show View (View: History) Alt+Shift+H In Windows Views<br />
Show View (View: Job<br />
Log)<br />
Show View (View: Where-<br />
Used List)<br />
Alt+Shift+L In Windows Views<br />
Alt+Shift+U In Windows Views<br />
Validate Ctrl+Shift+V In Windows Modeler Keys<br />
Validate Ctrl+Shift+V Navigator Modeler Keys<br />
Zoom (Type: In) Ctrl+= In Windows Modeler Keys<br />
Zoom (Type: Out) Ctrl+- In Windows Modeler Keys<br />
Zoom (Type: Reset) Alt+Shift+0 In Windows Modeler Keys<br />
1. Choose Window Preferences General Keys .<br />
2. In the Keys panel, select Modeler as Scheme.<br />
3. If you want to view only the commands supported by Modeler for keyboard shortcut, in the text field enter<br />
Modeler Keys.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
Note: You cannot add new commands but can choose to customize the commands using the<br />
following options:<br />
○ Copy Command - to provide alternate keyboard shortcut for an existing command.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 153
4. Choose Apply.<br />
○ Unbind Command - to clear the key bindings with the command and provide new keyboard<br />
shortcut for an existing command.<br />
○ Restore Command - to restore the default key bindings provided by Modeler for an existing<br />
command.<br />
6.5.14 Copying an Object<br />
You can choose to copy an object in the Navigator panel and paste it to a required package. You must have write<br />
permissions on the target package where you are pasting the object. The copy paste feature is supported for all<br />
Modeler objects that is, attribute view, analytic view, calculation view, procedure and analytic privilege. The object<br />
that is copied to the target package is always inactive, even if in the source package it is in active state.<br />
By default the keyboard shortcut for copy and paste is CTRL + C and CTRL + V respectively. To enable keyboard<br />
shortcut for copy and paste you must apply the Modeler keyboard shortcuts from the Window Preferences<br />
General Keys and select Modeler as scheme.<br />
Note: Copy paste is supported only for a single object.<br />
1. In the Navigator panel, select an object and in the contect menu, choose Copy.<br />
Note: If you have applied the Keyboard shortcuts then you can also press CTRL + C to copy an object.<br />
2. Navigate to the package where you want to paste the object, and choose Paste.<br />
Note: If you have applied the Keyboard shortcuts then you can also press CTRL + V to paste an object.<br />
6.6 Importing BW Objects<br />
● You have implemented <strong>SAP</strong> Notes 1703061, 1759172, 1752384,1733519, and 1769374.<br />
● You have upgraded your Modeler to <strong>SAP</strong> <strong>HANA</strong> 1.0 SP04 Rev 37.<br />
● You have added BW schema in the SQL privileges for the Modeler user to import BW models.<br />
● _SYS_REPO user has SELECT with GRANT privileges on the schema that contains the BW tables.<br />
You use this feature to import <strong>SAP</strong> NetWeaver Business Warehouse (<strong>SAP</strong> NetWeaver BW) models that are <strong>SAP</strong><br />
<strong>HANA</strong>-optimized InfoCubes, <strong>SAP</strong> <strong>HANA</strong>-optimized DataStore objects, and Query Snapshot InfoProviders to the<br />
<strong>SAP</strong> <strong>HANA</strong> modeling environment. These imported objects are exposed as <strong>SAP</strong> <strong>HANA</strong> information models and<br />
can be consumed for reporting using client tools such as, <strong>SAP</strong> BusinessObjects Explorer, <strong>SAP</strong> BusinessObjects BI<br />
4.0 Suite (Web Intelligence via Universes, Dashboards, Crystal Reports), Microsoft Office and so on. The model<br />
properties are set based on the <strong>SAP</strong> NetWeaver BW models metadata.<br />
If you select a DataStore object, the resultant <strong>SAP</strong> <strong>HANA</strong> model is an analytic view with the same name as that of<br />
the DataStore object. If you select an InfoCube, two objects- analytic view and calculation view are created. In this<br />
154<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
case, the name of calculation view and analytic view is same as that of the InfoCube and the name of the analytic<br />
view is suffixed with _INTERNAL. The analytic view generated in the case of an InfoCube is used internally for the<br />
generation of the respective calculation view and is not available for client consumption. If you select a<br />
QuerySnapshot InfoProvider, the resultant <strong>SAP</strong> <strong>HANA</strong> model is an analytic view.<br />
When you choose to import the <strong>SAP</strong> NetWeaver BW InfoProviders, the analysis authorizations set on the<br />
InfoProviders are also imported as analytic privileges in the <strong>SAP</strong> <strong>HANA</strong> Modeler. The name of the analytic privilege<br />
is the same as that of the BW Analysis Authorization object. These analysis authorizations set on the<br />
InfoProviders are applicable at runtime for reporting.<br />
Note: In the case of Query Snapshot, all the BW Analysis Authorization objects which are applicable on the<br />
underlying InfoProvider of the query, will also be applicable on the Query Snapshot. These BW analysis<br />
authorization objects will be imported as analytic privileges when importing the query snapshot.<br />
The generated models and analytic privileges are placed in the sap.bw package. You can choose to enhance the<br />
generated models. However, with the subsequent import of the same objects, the changes are overridden. Also,<br />
changes made to the models on BW side are not automatically reflected in the generated models. This may lead<br />
to inconsistent generated models based on the changes made to the physical tables. To avoid this, you need to re-<br />
import the models.<br />
Caution:<br />
● The calculated key figures (CKFs) and restricted key figures (RKFs) defined on the <strong>SAP</strong> BW models<br />
are not created for the generated <strong>SAP</strong> <strong>HANA</strong> models. In this case, you can create an RKF as restricted<br />
measure in the generated analytic view. For CKF you can create calculated measures in the generated<br />
calculation view or analytic view. These CKFs and RKFs are retained during subsequent import. If a<br />
change is made to the characteristics or key figures based on which these restricted measures and<br />
calculated measures are created, this may lead to inconsistency in the generated models. In this case,<br />
you need to manually adjust these restricted measures and calculated measures.<br />
● The restricted measures and calculated measures that you define for the analytic view that<br />
correspond to a query snapshot, is overwritten with the subsequent import.<br />
● The BW analysis authorization objects are not always mapped 1:1 with the generated analytic<br />
privileges on the <strong>SAP</strong> <strong>HANA</strong> Modeler side. If the BW Analysis Authorization object does not include<br />
0TCAIPROV, the authorization is not moved to <strong>SAP</strong> <strong>HANA</strong>. Also, restrictions created in the BW<br />
analysis authorization are skipped if they do not match with the restrictions supported by the <strong>SAP</strong><br />
<strong>HANA</strong> Modeler. In such cases, the data available for reporting for a <strong>SAP</strong> <strong>HANA</strong> Modeler user differs<br />
from the <strong>SAP</strong> NetWeaver BW user with the assigned restrictions.<br />
For reporting purposes, data which is visible for a user is:<br />
● For a DSO generated analytic view, all the data in the active table is available for reporting.<br />
● For an InfoCube generated calculation view, only successfully loaded requests are available for reporting<br />
(these are the green requests in manage InfoCube section).<br />
Restriction:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 155
● The following features are not supported on the generated <strong>SAP</strong> <strong>HANA</strong> models:<br />
○ DSO without any key figure<br />
○ Currency and unit of measure conversion<br />
Note: Only currency mapping is supported and not the conversion.<br />
○ Time dependent text and attributes<br />
○ Non-cumulative key figures<br />
○ Conversion routines in the BW system<br />
● The following features are not supported on generated analytic privileges:<br />
○ Exclude operator<br />
○ Aggregated value operator ‘:’<br />
○ Variables, User exits<br />
○ Authorization on Key Figures<br />
○ Authorization on hierarchy node<br />
○ Exception aggregation such as, average, counter, first value, last value, no aggregation, standard<br />
deviation is not supported for generated measures.<br />
● The query name for the Query Snapshot should not be the same as the BW InfoProvider name (this<br />
results in conflict on the <strong>SAP</strong> <strong>HANA</strong> side).<br />
● Query Snapshot InfoProvider for BOE supports only key figures with aggregation types MIN, MAX,<br />
SUM, and COUNT.<br />
1. Open the Modeler perspective.<br />
2. In the main menu, choose File Import .<br />
3. Expand the <strong>SAP</strong> <strong>HANA</strong> Content node.<br />
4. Choose Import <strong>SAP</strong> NetWeaver BW Models, and choose Next.<br />
5. To establish a connection with the <strong>SAP</strong> NetWeaver BW system (underlying BW Application Server), in the<br />
Source System page, enter the <strong>SAP</strong> NetWeaver BW system credentials and choose Next.<br />
Note: To add new connection details, select New Connection option from the Connection dropdown<br />
list. The connection details are saved and are available as dropdown options on subsequent logons.<br />
6. Select the target system (an <strong>SAP</strong> NetWeaver BW on <strong>SAP</strong> <strong>HANA</strong>) to which you want to import the models, and<br />
choose Next.<br />
7. Select the BW InfoProviders that you want to import and expose as <strong>SAP</strong> <strong>HANA</strong> information models.<br />
Remember: In order to import the QuerySnapshot InfoProvider, make sure that the BW Query is<br />
unlocked in transaction RSDDB, and an index is created via the same transaction before it can be used<br />
as InfoProviders.<br />
8. If you want to replace previously imported models in the target system with a new version, select Overwrite<br />
existing models.<br />
9. If you want import the selected models along with the display attributes for IMO Cube and IMO DSO, select<br />
Include display attributes.<br />
156<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model
The generated information models and analytic privileges are placed in the sap.bw package. In order to view the<br />
data of generated models, you need to assign the associated analytic privileges that are generated as part of the<br />
model import to the user. If these privileges are not assigned, user is not authorized to view the data.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up the Analytic Model<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 157
7 Developing Procedures<br />
SQL in <strong>SAP</strong> <strong>HANA</strong> includes extensions for creating procedures, which enables you to embed data-intensive<br />
application logic into the database, where it can be optimized for performance (since there are no large data<br />
transfers to the application and features such as parallel execution is possible). Procedures are used when other<br />
modeling objects, such as analytic or attribute views, are not sufficient.<br />
Some of the reasons to use procedures instead of standard SQL:<br />
● SQL is not designed for complex calculations, such as for financials.<br />
● SQL does not provide for imperative logic.<br />
● Complex SQL statements can be hard to understand and maintain.<br />
● SQL queries return one result set. Procedures can return multiple result sets.<br />
● Procedures can have local variables, eliminating the need to explicitly create temporary tables for<br />
intermediate results.<br />
Procedures can be written in the following languages:<br />
● SQLScript: The language that <strong>SAP</strong> <strong>HANA</strong> provides for writing procedures.<br />
● R: An open-source programming language for statistical computing and graphics, which can be installed and<br />
integrated with <strong>SAP</strong> <strong>HANA</strong>.<br />
There are additional libraries of procedures, called Business Function Library and Predictive Analysis Library, that<br />
can be called via SQL or from within another procedure.<br />
SQL Extensions for Procedures<br />
SQL includes the following statements for enabling procedures:<br />
● CREATE TYPE: Creates a table types, which are used to define parameters for a procedure that represent<br />
tabular results. For example:<br />
CREATE TYPE tt_publishers AS TABLE (<br />
publisher INTEGER,<br />
name VARCHAR(50),<br />
price DECIMAL,<br />
cnt INTEGER);<br />
● CREATE PROCEDURE: Creates a procedure. The LANGUAGE clause specifies the language you are using to<br />
158<br />
code the procedure. For example:<br />
CREATE PROCEDURE ProcWithResultView(IN id INT, OUT o1 CUSTOMER)<br />
LANGUAGE SQLSCRIPT READS SQL DATA WITH RESULT VIEW ProcView AS<br />
BEGIN<br />
o1 = SELECT * FROM CUSTOMER WHERE CUST_ID = :id;<br />
END;<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Developing Procedures
● CALL: Calls a procedure. For example:<br />
CALL getOutput (1000, 'EUR', NULL, NULL);<br />
Tools for Writing Procedures<br />
Use the SQLScript editor, which includes debugging capabilities, to build SQLScript procedures.<br />
You can also use the Navigator in the Modeler perspective to build procedures, but there are no debugging<br />
capabilities. You should only use this method:<br />
● If you need to develop a procedure using a local table type as an input or output parameter. A local table type<br />
is created within the Navigator procedure tool and for only the current procedure. If you can use a global table<br />
type, then use the SQLScript Editor.<br />
● If you need to edit a procedure previously created in the Navigator that contains table type parameters.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> SQL Reference<br />
<strong>SAP</strong> <strong>HANA</strong> SQLScript Reference<br />
<strong>SAP</strong> <strong>HANA</strong> R Integration <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> Business Function Library (BFL) Reference<br />
<strong>SAP</strong> <strong>HANA</strong> Predictive Analysis Library (PAL) Reference<br />
Creating Procedures<br />
7.1 Editing SQLScript<br />
The <strong>SAP</strong> <strong>HANA</strong> SQLScript editor allows you to create, edit and activate procedures.<br />
Before you begin working in the <strong>SAP</strong> <strong>HANA</strong> SQLScript editor, open the <strong>SAP</strong> <strong>HANA</strong> Development perspective and<br />
do the following:<br />
● Create a development workspace. For more information, see Creating a Repository Workspace [page 39].<br />
● Checkout a package. For more information, see Working with the Repository [page 27] .<br />
Note: After checking out a package that contains active procedures, you can modify and debug the<br />
procedures.<br />
● Create and share a project. For more information, see Using <strong>SAP</strong> <strong>HANA</strong> Projects [page 37].<br />
.<br />
Note: You can also share your project after you create your procedure.<br />
To write and edit a procedure in the <strong>SAP</strong> <strong>HANA</strong> SQLScript editor, perform the following steps:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Developing Procedures<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 159
1. After you have created your workspace and your project, go to the Project Explorer view in the <strong>SAP</strong> <strong>HANA</strong><br />
Development perspective , right-click on the file name, select New, and select File. The New File wizard will<br />
appear.<br />
2. Enter or select the parent folder and enter the file name using the following naming convention<br />
.procedure. Choose Finish. The icon shows that your procedure is created locally. Choose Save.<br />
Your procedure will open containing the default Create Procedure template. In the Properties view, you will<br />
see the properties of your procedure, such as Access Mode, Name and Language. You can also change the<br />
default schema that this procedure is using.<br />
Note: You can also create a folder first and add a file. Right-click on the project name, select New, and<br />
select Folder. The New Folder wizard will appear. Enter or select the project, enter the folder name,<br />
and choose Finish.<br />
3. To share your project, right-click on the project name, select Team, and select Share Project. The Share<br />
Project wizard will appear. Choose Finish. The icon shows that your procedure is not committed and not<br />
activated.<br />
4. You can begin writing your code inside your new procedure and save it locally. The syntax is checked<br />
simultaneously and is highlighted. Auto-completion of the syntax appears as you type; press Ctrl + Spacebar<br />
to get a list of relevant SQLScript statements.<br />
Note: You can only write one stored procedure per file. The file name and the procedure name must<br />
be the same.<br />
5. To commit your new procedure or make changes to an existing one, first save it, right-click on the procedure,<br />
select Team, and select Commit. Your procedure is now synchronized to the repository as a design-time<br />
object and the icon shows that your procedure is committed .<br />
Caution: The design-time presentation of the procedure is currently in XML format that you must not<br />
edit.<br />
6. When you have finished writing your procedure and you are ready to activate it, right-click on the procedure,<br />
select Team, and select Activate. Your procedure is created in the catalog as a runtime object and the icon<br />
shows that your procedure is activated . This will allow you and other users to call the procedure and debug it.<br />
If an error is detected during activation, an error message will appear in the Problems view.<br />
Related Links<br />
Note: You can also activate your procedure at the project and folder level.<br />
<strong>SAP</strong> <strong>HANA</strong> Development Perspective [page 25]<br />
<strong>SAP</strong> <strong>HANA</strong> Repository Packages and Namespaces [page 43]<br />
In <strong>SAP</strong> <strong>HANA</strong>, a package typically consists of a collection of repository objects, which can be transported<br />
between systems. Multiple packages can be combined in a delivery unit (DU).<br />
About <strong>SAP</strong> <strong>HANA</strong> SQLScript<br />
<strong>SAP</strong> <strong>HANA</strong> SQL Reference<br />
<strong>SAP</strong> <strong>HANA</strong> System Tables and Monitoring Views Reference<br />
160<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Developing Procedures
7.2 Debugging SQLScript<br />
The <strong>SAP</strong> <strong>HANA</strong> SQLScript debugger allows you to debug and analyze procedures. In a debug session, your<br />
procedures will be executed in a serial mode, not in parallel (not-optimized). This allows you to test the<br />
correctness of the procedure logic and is not for evaluating the performance.<br />
Before you begin using the <strong>SAP</strong> <strong>HANA</strong> SQLScript debugger, you must activate your procedures and they must<br />
belong to a project on your local work station. For more information, see Editing SQLScript.<br />
To debug a procedure in the <strong>SAP</strong> <strong>HANA</strong> SQLScript debugger, perform the following steps:<br />
1. Open the Debug perspective in the <strong>SAP</strong> <strong>HANA</strong> studio and select the procedure you want to debug by clicking<br />
on the relevant tab in the Editor view.<br />
2. Double-click on the left vertical ruler to add breakpoints to your procedure. You can see a list of all of the<br />
breakpoints in the Breakpoints view.<br />
From the Breakpoints view, you can:<br />
○ Deselect specific breakpoints or skip all of them.<br />
○ Delete a specific breakpoint or delete all.<br />
○ Double-click on a breakpoint to see which line it belongs to in the Editor view.<br />
○ See the status of the breakpoint:<br />
○ Pending<br />
○ Valid<br />
○ Invalid<br />
3. To create a debug session you must first create a debug configuration. Choose and select Debug<br />
Configurations.... The Debug Configurations wizard will appear.<br />
Note: The current debug configuration allows you to debug any stored procedure that is opened in the<br />
editor. Therefore, you do not have to create a new debug configuration for every procedure you want<br />
to debug.<br />
4. Double-click SQLScript Procedure, enter a name, choose Apply, and choose Close.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Developing Procedures<br />
Note: If you want to start debugging your procedure, choose Apply and choose Debug.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 161
5. To start your debug session, choose and select your debug configuration. The debug session will begin<br />
and you will see the status of the session in the Debug view. The status of a breakpoint may change after the<br />
server has validated it. The breakpoint position might change if it is placed on an invalid line where the<br />
debugger cannot stop. The debugger will stop at the first breakpoint and the session will be suspended until<br />
you resume it.<br />
If your run is successful, the valid status will appear next to the breakpoints in the Breakpoints view.<br />
Note: You must set breakpoints in the lines you want to break at and resume the session again.<br />
You can evaluate your local scalar and table variables in the Variable view. The view shows the values of the<br />
scalar variables and the number of rows in each table.<br />
6. To view the content of the tables listed in the Variable view, right-click on the table name and select Open Data<br />
Preview. The results will appear in the Preview view. This view will automatically close when you resume your<br />
debug session.<br />
The session will be terminated when you reach the end of the procedure run.<br />
7.3 Developing Procedures in the Modeler Editor<br />
To create procedures, use the SQLScript Editor, as described in Editing SQLScript [page 159].<br />
If you need to create procedures with local table types, that is, table types created only for the procedure, perform<br />
the steps described in this section.<br />
1. On the Quick Launch tab page, choose Procedure.<br />
If the Quick Launch page is not open, go to Help Quick Launch .<br />
2. Enter a name and description for the procedure.<br />
3. For unqualified access in SQL, select the required schema from the Default Schema dropdown list.<br />
Note:<br />
○ If you do not select a default schema, while scripting you need to provide fully qualified names of<br />
the catalog objects that include the schema.<br />
○ If you specify a default schema, and write SQL such as select * from myTable, the<br />
specified default schema is used at runtime to refer to the table.<br />
4. Select the package in which you want to save the procedure.<br />
5. Select the required option from the Run With dropdown list to select which privileges are to be considered<br />
while executing the procedure.<br />
162<br />
Note:<br />
There are two types of rights, as follows:<br />
Definer's right: If you want the system to use the rights of the definer while executing the procedure<br />
for any user.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Developing Procedures
Invoker's right: If you want the system to use the rights of the current user while executing the<br />
procedure.<br />
6. Select the required access mode as follows:<br />
Access Mode Purpose<br />
Read Only Use this mode to create procedures for fetching table data.<br />
Read Write Use this mode to create procedures for fetching and<br />
updating table data.<br />
7. Select the language in which you are writing the procedure.<br />
8. Choose Finish.<br />
9. In the function editor pane, write a script for the function using the following data types:<br />
○ Table or scalar data types for input parameters.<br />
○ Table data types for output parameters.<br />
Note: You can only write one function in the function body. However, you can refer to other functions.<br />
10. Choose File Save .<br />
11. Activate the procedure using one of the following options in the toolbar:<br />
○ Save and Activate: Activate the current procedure and redeploy the affected objects if an active version of<br />
the affected object exists. Otherwise only the current procedure gets activated.<br />
○ Save and Activate All: Activate the current procedure along with the required and affected objects.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Developing Procedures<br />
Note: You can also activate the current procedure by selecting the procedure in the Navigator view<br />
and choosing Activate in the context menu. For more information about activation, see Activating<br />
Objects [page 132].<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 163
8 Defining Web-based Data Access<br />
<strong>SAP</strong> <strong>HANA</strong> extended application services (<strong>SAP</strong> <strong>HANA</strong> XS) provide applications and application developers with<br />
access to the <strong>SAP</strong> <strong>HANA</strong> database using a consumption model that is exposed via HTTP.<br />
In addition to providing application-specific consumption models, <strong>SAP</strong> <strong>HANA</strong> XS also host system services that<br />
are part of the <strong>SAP</strong> <strong>HANA</strong> database, for example: search services and a built-in Web server that provides access<br />
to static content stored in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
The consumption model provided by <strong>SAP</strong> <strong>HANA</strong> XS focuses on server-side applications written in JavaScript and<br />
making use of a powerful set of specially developed API functions. However, you can use other methods to<br />
provide access to the data you want to expose in <strong>SAP</strong> <strong>HANA</strong>. For example, you can set up an ODATA service or<br />
use the XML for Analysis (XMLA) interface to send a Multi-dimensional Expressions (MDX) query. This section<br />
describes how to set up a service that enables you to expose data using OData or XMLA.<br />
8.1 Data Access with OData in <strong>SAP</strong> <strong>HANA</strong> XS<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the persistence model (for example, tables, views,<br />
and stored procedures) is mapped to the consumption model that is exposed to clients - the applications you<br />
write to extract data from the <strong>SAP</strong> <strong>HANA</strong> database.<br />
You can map the persistence and consumption models with OData, a resource-based Web protocol for querying<br />
and updating data. An OData application running in <strong>SAP</strong> <strong>HANA</strong> XS is used to provide the consumption model for<br />
client applications exchanging OData queries with the <strong>SAP</strong> <strong>HANA</strong> database.:<br />
You can use OData to enable clients to consume authorized data stored in the <strong>SAP</strong> <strong>HANA</strong> database. OData<br />
defines operations on resources using RESTful HTTP commands (for example, GET, PUT, POST, and DELETE)<br />
and specifies the URI syntax for identifying the resources. Data is transferred over HTTP using either the Atom<br />
(XML) or the JSON (JavaScript) format.<br />
Applications running in <strong>SAP</strong> <strong>HANA</strong> XS enable accurate control of the flow of data between the presentational<br />
layer, for example, in the Browser, and the data-processing layer in <strong>SAP</strong> <strong>HANA</strong> itself, where the calculations are<br />
performed, for example, in SQL or SQLScript. If you develop and deploy an OData service running in <strong>SAP</strong> <strong>HANA</strong><br />
XS, you can take advantage of the embedded access to <strong>SAP</strong> <strong>HANA</strong> that <strong>SAP</strong> <strong>HANA</strong> XS provides; the embedded<br />
access greatly improves end-to-end performance.<br />
8.1.1 OData in <strong>SAP</strong> <strong>HANA</strong> XS<br />
OData is a resource-based web protocol for querying and updating data. OData defines operations on resources<br />
using HTTP commands (for example, GET, PUT, POST, and DELETE) and specifies the uniform resource<br />
indicator (URI) syntax to use to identify the resources.<br />
Data is transferred over HTTP using the Atom or JSON format:<br />
164<br />
Note: OData makes it easier for <strong>SAP</strong>, for partners, and for customers to build standards-based<br />
applications for many different devices and on various platforms, for example, applications that are based<br />
on a lightweight consumption of <strong>SAP</strong> and non-<strong>SAP</strong> business application data.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
The main aim of OData is to define an abstract data model and a protocol which, combined, enable any client to<br />
access data exposed by any data source. Clients might include Web browsers, mobile devices, businessintelligence<br />
tools, and custom applications (for example, written in programming languages such as PHP or Java);<br />
data sources can include databases, content-management systems, the Cloud, or custom applications (for<br />
example, written in Java).<br />
The OData approach to data exchange involves the following elements:<br />
● OData data model<br />
Provides a generic way to organize and describe data. OData uses the Entity 1 Data Model (EDM).<br />
● OData protocol<br />
Enables a client to query an OData service. The OData protocol is a set of interactions, which includes the<br />
usual REST-based create, read, update, and delete operations along with an OData-defined query language.<br />
The OData service sends data in either of the following ways:<br />
○ XML-based format defined by Atom/AtomPub<br />
○ JavaScript Object Notation (JSON)<br />
● OData client libraries<br />
Enables access to data via the OData protocol. Since most OData clients are applications, pre-built libraries<br />
for making OData requests and getting results reduces and simplifies work for the developers who create<br />
those applications.<br />
A broad selection of OData client libraries are already widely available, for example: Android, Java, JavaScript,<br />
PHP, Ruby, and the best known mobile platforms.<br />
● OData services<br />
Exposes an end point that allows access to data in the <strong>SAP</strong> <strong>HANA</strong> database. The OData service implements<br />
the OData protocol (using the OData Data Services runtime) and uses the Data Access layer to map data<br />
between its underlying form (database tables, spreadsheet lists, and so on) and a format that the requesting<br />
client can understand.<br />
8.1.2 OData Service Definitions<br />
The OData service definition is the mechanism you use to define what data to expose with OData, how, and to<br />
whom. Data exposed as an OData collection is available for analysis and display by client applications, for<br />
example, a browser that uses functions provided by an OData client library running on the client system.<br />
To expose information by means of OData to applications using <strong>SAP</strong> <strong>HANA</strong> XS, you must define database views<br />
that provide the data with the required granularity. Then you create an OData service definition, which is a file you<br />
use to specify which database views or tables are exposed as OData collections.<br />
Note: <strong>SAP</strong> <strong>HANA</strong> XS currently supports OData version 2.0, which you can use to send OData queries<br />
(using the http GET method). Language encoding is restricted to UTF-8.<br />
An OData service for <strong>SAP</strong> <strong>HANA</strong> XS is defined in a text file with the file suffix .xsodata, for example,<br />
OdataSrvDef.xsodata. The file must contain at least the entry service {}, which would generate a<br />
completely operational OData service with an empty service catalog and an empty metadata file. However, usually<br />
you use the service definition to expose objects in the database catalog, for example: tables, SQL views, or<br />
calculation rules.<br />
In the OData service-definition file, you can use the following ways to name the <strong>SAP</strong> <strong>HANA</strong> objects you want to<br />
expose by OData:<br />
● Repository objects<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 165
Expose an object using the object's repository (design-time) name in the OData service-definition file. This<br />
method of exposing database objects by OData has the advantage that the OData service is automatically<br />
updated if the underlying repository object changes.<br />
● Database objects<br />
Expose an object using the object's database catalog (runtime) name (along with the schema name). The<br />
support for database objects is mainly intended for existing or replicated objects that do not have a repository<br />
design-time representation.<br />
Note: Although both declaration methods are supported, the recommended method is to use the<br />
repository name of the object(s) you want to expose using OData.<br />
OData Service-Definition Type Mapping<br />
During the activation of the OData service definition, SQL types are mapped to EDM types according to a mapping<br />
table. For example, the SQL type "Time" is mapped to the EDM type "EDM.Time"; the SQL type "Decimal" is<br />
mapped to the EDM type "EDM.Decimal"; the SQL types "Real" and "Float" are mapped to the EDM type<br />
"EDM.Single".<br />
In the following example, the SQL types of columns in a table are mapped to the EDM types in the properties of an<br />
entity type.<br />
{name = "ID"; sqlType = INTEGER; nullable = false;}, {name = "RefereeID";<br />
sqlType = VARCHAR; nullable = true;}<br />
<br />
OData Service-Definition Features<br />
The OData service definition provides a list of keywords that you use in the OData service-definition file to enable<br />
important features. For example, the following list illustrates the most-commonly used features used in an OData<br />
service-definition and, where appropriate, indicates the keyword to use to enable the feature:<br />
● Aggregation<br />
The results of aggregations on columns change dynamically, depending on the grouping conditions. As a<br />
result, aggregation cannot be done in SQL views; it needs to be specified in the OData service definition itself.<br />
Depending on the type of object you want to expose with OData, the columns to aggregate and the function<br />
used must be specified explicitly (explicit aggregation) or derived from metadata in the database (derived<br />
aggregation). Note that aggregated columns cannot be used in combination with the $filter query<br />
parameter, and aggregation is only possible with generated keys.<br />
● Association<br />
Define associations between entities to express relationships between entities. With associations it is possible<br />
to reflect foreign key constraints on database tables, hierarchies and other relations between database<br />
objects.<br />
● Key Specification<br />
166<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
The OData specification requires an EntityType to denote a set of properties forming a unique key. In <strong>SAP</strong><br />
<strong>HANA</strong>, only tables can have a unique key, the primary key. All other (mostly view) objects require you to<br />
specify a key for the entity. The OData service definition language (OSDL) enables you to do this by denoting a<br />
set of existing columns or by generating a local key. Bear in mind that local keys are transient; they exist only<br />
for the duration of the current session and cannot be dereferenced.<br />
Note: OSDL is the language used to define a service definition; the language includes a list of keywords<br />
that you use in the OData service-definition file to enable the required features.<br />
● Parameter Entity Sets<br />
You can use a special parameter entity set to enter input parameters for <strong>SAP</strong> <strong>HANA</strong> calculation views and<br />
analytic views. During activation of the entity set, the specified parameters are retrieved from the metadata of<br />
the calculation (or analytical) view and exposed as a new EntitySet with the name suffix "Parameters", for<br />
example "CalcViewParameters".<br />
● Projection<br />
If the object you want to expose with an OData service has more columns than you actually want to expose,<br />
you can use SQL views to restrict the number of selected columns in the SELECT. However, for those cases<br />
where SQL views are not appropriate, you can use the with or without keywords in the OData service<br />
definition to include or exclude a list of columns.<br />
8.1.3 OData URI Parameters, Query Options, and Features<br />
Since OData fully embraces Web technologies, and more specifically URI concepts, all the actions that manage<br />
the interaction with the service at runtime are controlled by HTTP methods, the URI structure, or URI query<br />
parameters.<br />
The examples listed here illustrate how to use the OData service-definition file to specify what data to extract and<br />
what to do with it. You can find examples of the following features:<br />
● HTTP Methods<br />
For example, HTTPGET<br />
● Resource types<br />
For example: Service documents, entity sets, $metadata, and so on<br />
● Query options<br />
For example, $format, $filter, $select, and so on<br />
HTTP Methods<br />
Since the current OData Infrastructure only supports read services (no Create/Update/Delete), the only<br />
supported HTTP Method is GET and POST for $batch (containing only GET requests). The result is that only read<br />
requests are possible.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 167
Resource Types<br />
You can use the resource types (or constructs) described and explained here to define how the service definition<br />
exposes data. For example, the Service Document, Resource Type, or Entity sets enable you to select and view<br />
the contents of the entity sets that are queried.<br />
Service Document<br />
The most basic resource type is the call to the .xsodata resource itself. This supplies information about the<br />
entity set within this resource; otherwise known as the Service Document.<br />
● Sample XSODATA Service:<br />
service namespace "SAMPLE" {<br />
"sample.hello::hello_tbl" as "Entries";<br />
}<br />
● URI Construct:<br />
/.xsodata/<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/<br />
● Sample XML Output:<br />
● Sample JSON Output:<br />
168<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
Entity Sets<br />
This construct allows you to view the entire content of the queried Entity Set.<br />
● URI Construct<br />
/.xsodata/<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries<br />
● Sample ATOM Output:<br />
● Sample JSON Output:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 169
Single Entity<br />
Any single entity (record) can be accessed by supplying the key field values after the Entity Set.<br />
● URI Construct:<br />
○ Single Key: /.xsodata/()<br />
○ Multiple Keys: /.xsodata/(=,)/<br />
● Sample URI:<br />
○ Single Key: /.xsodata/()<br />
○ Multiple Keys: http://hanaxs:8000/sap./sflight/spfli.xsodata/<br />
FLIGHTS(CARRID='AA',CONNID='0017')#<br />
● Sample ATOM Output:<br />
170<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
● Sample JSON Output:<br />
Single Property<br />
Likewise, any single property of an entry can be directly accessed as well.<br />
● URI Construct:<br />
○ Single Key: /.xsodata/()/<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 171
○ Multiple Keys: http://hanaxs:8000/sap./sflight/spfli.xsodata/<br />
FLIGHTS(CARRID='AA',CONNID='0017')/CITYFROM<br />
● Sample URI:<br />
○ Single Key: http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries(1)/<br />
TEXT<br />
○ Multiple Key: http://hanaxs:8000/sap./sflight/spfli.xsodata/<br />
FLIGHTS(CARRID='AA',CONNID='0017')/CITYFROM<br />
● Sample ATOM Output:<br />
● Sample JSON Output:<br />
$metadata<br />
This parameter requests that the OData service return a special document that describes the structure of the<br />
service itself. All properties, their data types, and all associations and relationships are described in this<br />
document.<br />
● URI Construct:<br />
/.xsodata/$metadata<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/$metadata<br />
● Sample Output:<br />
172<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
$count<br />
This request allows you to return the number of records in an Entity Set instead of the details of the Entity Set. It is<br />
basically the same as using a SELECT COUNT(*) in an SQL Statement without top limitation.<br />
● URI Construct:<br />
/.xsodata//$count<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/$count<br />
● Sample Output:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 173
$value<br />
By specifying this segment after a single property, the service returns the value of the property as plain text.<br />
● URI Construct:<br />
/.xsodata//$value<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries(1)/Text/$value<br />
● Sample Output:<br />
$batch<br />
The $batch resource allows you to send multiple requests in one multipart request by using the POST http<br />
method.<br />
● URI Construct:<br />
/.xsodata/$batch<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/$batch<br />
● Sample Request:<br />
174<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
● Sample ATOM and JSON Output:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 175
Query Parameters<br />
$format<br />
This parameter controls the output format. The default format is ATOM. However, the other supported option is<br />
JSON, which can be triggered by setting the $format=json.<br />
● URI Construct:<br />
/.xsodata//$format=<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/$format=json<br />
● Sample Output:<br />
$filter<br />
A parameter that allows you to restrict the entities in the entity set. This option builds a dynamic WHERE condition<br />
into the underlying query.<br />
● URI Construct:<br />
/.xsodata//$filter = ''<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/?<br />
$filter=CREATED%20eq%20datetime'2012-05-14T08:28:44.405'<br />
● Sample ATOM Output:<br />
176<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
● Sample JSON Output:<br />
$orderby<br />
This is a parameter that controls how the entities in the entity set are sorted.<br />
● URI Construct:<br />
/.xsodata//$orderby= asc|desc<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/?<br />
$orderby=CREATED%20desc<br />
● Sample ATOM Output:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 177
● Sample JSON Output:<br />
$skip<br />
This is a parameter that allows you to skip ahead in an entity set only. It is useful when creating "paging" through<br />
an entity set.<br />
● URI Construct:<br />
/.xsodata//$skip=n<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/?$skip=2<br />
● Sample ATOM Output:<br />
178<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
● Sample JSON Output:<br />
$top<br />
This option allows you to limit the number of records returned regardless of how many records exist in the Entity<br />
Set. It is basically the same as using a SELECT ... UP TO n ROWS in an SQL Statement.<br />
● URI Construct:<br />
/.xsodata//$top=n<br />
● Sample URI:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 179
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/?$top=3<br />
● Sample ATOM Output:<br />
● Sample JSON Output:<br />
$inlinecount<br />
This parameter triggers the OData service to embed an extra property with the total count in the complete entity<br />
set. This is the count of all entities after the $filter option has been applied.<br />
● URI Construct:<br />
180<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
.xsodata//$inlinecount=allpages<br />
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/?<br />
$inlinecount=allpages<br />
● Sample ATOM Output:<br />
● Sample JSON Output:<br />
$select<br />
This property allows you to control which properties for each entity are returned in the entity set.<br />
● URI Construct:<br />
/.xsodata//$select=,,<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 181
● Sample URI:<br />
http://hanaxs:8000/sample/hello/hello_odata.xsodata/Entries/?$select=TEXT<br />
● Sample ATOM Output:<br />
● Sample JSON Output:<br />
182<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
8.1.4 OData Security Considerations<br />
Enabling access to data by means of OData can create some security-related issues that you need to consider and<br />
address, for example, the data you want to expose, who can start the OData service, and so on.<br />
If you want to use OData to expose data to users and clients in <strong>SAP</strong> <strong>HANA</strong> application services, you need to bear<br />
in mind the security considerations described in the following list:<br />
● Data Access<br />
Restrict user select authorization for tables/views exposed by the OData service<br />
● OData Service<br />
Restrict authorization rights to start the OData service<br />
● OData Statistical content<br />
Restrict access to the URL/Path used to expose OData content in the Web browser<br />
8.1.5 Defining the Data an OData Service Exposes<br />
An OData service exposes data stored in database tables or views as OData collections for analysis and display by<br />
client applications. However, first of all, you need to ensure that the tables and views to expose as an OData<br />
collection actually exist.<br />
To define the data to expose using an OData service, you must perform at least the following tasks:<br />
1. Create a database schema.<br />
2. Create a simple database table to expose with an OData service.<br />
3. Create a simple database view to expose with an OData service.<br />
This step is optional; you can expose tables directly. In addition, you can create a repository view (for<br />
example, Analytic, Attribute, Calculation).<br />
4. Grant select privileges to the tables and views to be exposed with the OData service.<br />
8.1.6 Creating an OData Service Definition<br />
The OData service definition is a configuration file you use to specify which data (for example, views or tables) is<br />
exposed as an OData collection for analysis and display by client applications.<br />
An OData service for <strong>SAP</strong> <strong>HANA</strong> XS is defined in a text file with the file suffix .xsodata, for example,<br />
OdataSrvDef.xsodata. The file resides in the package hierarchy of the OData application and must contain at<br />
least the entry service {}, which would generate an operational OData service with an empty service catalog and<br />
an empty metadata file.<br />
Prerequisites for the creation of an OData service definition:<br />
● <strong>SAP</strong> <strong>HANA</strong> studio/client installed and configured<br />
● <strong>SAP</strong> <strong>HANA</strong> database user available with repository privileges (for example, to add packages)<br />
● A <strong>SAP</strong> <strong>HANA</strong> development system added to (and available in) <strong>SAP</strong> <strong>HANA</strong> studio, for example, in either the<br />
Navigator view or the <strong>SAP</strong> <strong>HANA</strong> Repositories view<br />
● A working development environment including a repository workspace, a package structure for your OData<br />
application, and a shared project to enable you to synchronize changes to the OData project files in the local<br />
file system with the repository<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 183
● Defined data to expose with the OData application, for example, at least the following:<br />
○ A database schema<br />
○ A database table<br />
1. In the shared project you are using for your OData application, use the Project Explorer view to locate the<br />
package where you want to create the new OData service definition.<br />
Note: The file containing the OData service definition must be placed in the root package of the OData<br />
application for which the service is intended.<br />
2. Create the file that will contain your OData service definition.<br />
In the Project Explorer view, right-click the folder where you want to create the new OData service-definition<br />
file and choose New File in the context-sensitive popup menu.<br />
3. Define the OData service.<br />
The OData service definition uses the OData Service Definition Language (OSDL), which includes a list of<br />
keywords that you specify in the OData service-definition file to enable important features.<br />
The following example shows a simple OData service definition exposing a simple table:<br />
service namespace "my.namespace" {<br />
"sample.odata:table.hdbtable" as "MyTable";<br />
}<br />
This service definition exposes a table defined in the file sample.odata:table.hdbtable and creates an<br />
EntitySet for this entity named MyTable. The specification of an alias is optional. If omitted, the default name<br />
of the EntitySet is the name of the repository object file, in this example, table.<br />
4. Place the valid OData service definition in the root package of the OData application to which it applies.<br />
5. Save, commit, and activate the OData service definition in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
Related Links<br />
OData Service Definitions [page 165]<br />
The OData service definition is the mechanism you use to define what data to expose with OData, how, and to<br />
whom. Data exposed as an OData collection is available for analysis and display by client applications, for<br />
example, a browser that uses functions provided by an OData client library running on the client system.<br />
8.1.7 OData Service Definition Language Syntax<br />
The OData Service Definition Language (OSDL) provides a set of keywords that enable you to set up an ODATA<br />
service definition file that specifies what data to expose, in what way, and to whom.<br />
The following list shows the syntax of the OData Service Definition Language (OSDL) in an EBNF-like format;<br />
conditions that apply for usage are listed after the table.<br />
definition :='service' [namespace] body<br />
namespace :='namespace' quotedstring<br />
quotedstring :=quote string quote<br />
string :=UTF8<br />
quote :='"'<br />
body :='{' content '}'<br />
content :=entry [content]<br />
entry :=( entity | association ) ';'<br />
entity :=object [entityset] [with] [keys] [navigates]<br />
[aggregates] [parameters]<br />
184<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
object :=['entity'] ( repoobject | catalogobject )<br />
repoobject :=quote repopackage '/' reponame '.' repoextension<br />
quote<br />
repopackage :=string<br />
reponame :=string<br />
repoextension :=string<br />
catalogobject :=catalogobjectschema '.' catalogobjectname<br />
catalogobjectschema :=quotedstring<br />
catalogobjectname :=quotedstring<br />
entityset :='as' entitysetname<br />
entitysetname :=quotedstring<br />
with :=( 'with' | 'without' ) propertylist<br />
propertylist :='(' columnlist ')'<br />
columnlist :=columnname [',' columnlist]<br />
columnname :=quotedstring<br />
keys :='keys' ( keylist | keygenerated )<br />
keylist :=propertylist<br />
keygenerated :='generate' ( keygenlocal )<br />
keygenlocal :='local' columnname<br />
navigates :='navigates' '(' navlist ')'<br />
navlist :=naventry [',' navlist]<br />
naventry :=assocname 'as' navpropname [fromend]<br />
assocname :=quotedstring<br />
navpropname :=quotedstring<br />
fromend :='from' ( 'principal' | 'dependent' )<br />
aggregates :='aggregates' 'always' [aggregatestuple]<br />
aggregatestuple :='(' aggregateslist ')'<br />
aggregateslist :=aggregate [',' aggregateslist]<br />
aggregate :=aggregatefunction 'of' columnname<br />
aggregatefunction :=( 'SUM' | 'AVG' | 'MIN' | 'MAX' )<br />
parameters :='parameters' 'via' 'entity'<br />
[parameterentitysetname] [parametersresultsprop]<br />
parameterentitysetname :=quotedstring<br />
parametersresultsprop :='results' 'property' quotedstring<br />
association :=associationdef principalend dependentend<br />
[assoctable]<br />
associationdef :='association' assocname<br />
principalend :='principal' end<br />
dependentend :='dependent' end<br />
end :=endref multiplicity<br />
endref :=endtype '(' joinproperties ')'<br />
endtype :=entitysetname<br />
joinproperties :=columnlist<br />
multiplicity :='multiplicity' quote multiplicityvalue quote<br />
multiplicityvalue :=( '1' | '0..1' | '1..*' | '*' )<br />
assoctable :='over' repoobject overprincipalend<br />
overdependentend<br />
overprincipalend :='principal' overend<br />
overdependentend :='dependent' overend<br />
overend :=propertylist<br />
Conditions<br />
The following conditions apply when using the listed keywords:<br />
1. If the namespace is not specified, the schema namespace in the EDMX metadata document will be the<br />
repository package of the service definition file concatenated with the repository object name. E.g. if the<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 185
epository design time name of the .xsodata file is sap.hana.xs.doc/hello.xsodata the<br />
namespace will implicitly be sap.hana.xs.doc.hello.<br />
2. keyslist must not be specified for objects of type 'table'. They must only be applied to objects referring a<br />
view type. keygenerated in turn, can be applied to table objects.<br />
3. If the entityset is not specified in an entity, the EntitySet for this object is named after the repository<br />
object name or the catalogobjectname. E.g. if object is "sap.hana.xs.doc/odata_docu" the<br />
entitysetname is implicitly set to odata_docu which then can also be referenced in associations.<br />
4. The fromend in a naventry must be specified if the endtype is the same for both the principalend<br />
and the dependentend of an association.<br />
5. The number of joinproperties in the principalend must be the same as in the dependentend.<br />
6. Ordering in the joinproperties of ends is relevant. The first columnname in the joinproperties of<br />
the principalend is compared with the first columnname of the dependentend, the second with the<br />
second, and so on.<br />
7. The overprincipalend corresponds to the principalend. The number of properties in the<br />
joinproperties and the overproperties must be the same and their ordering is relevant. The same<br />
holds for the dependent end.<br />
8. aggregates can only be applied in combination with keygenerated.<br />
9. If aggregatestuple is omitted, the aggregation functions are derived from the database. This is only<br />
possible for calculation views and analytic views.<br />
10. Specifying parameters is only possible for calculation views and analytic views.<br />
11. The default parameterentitysetname is the entitysetname of the entity concatenated with the<br />
suffix "Parameters".<br />
12. If the parametersresultsprop is omitted, the navigation property from the parameter entity set to the<br />
entity is called "Results".<br />
8.1.8 OData Service Definition: SQL-EDM Type Mapping<br />
During the activation of the OData service definition, the <strong>SAP</strong> <strong>HANA</strong> SQL types are mapped to the required OData<br />
EDM types according to the rules specified in a mapping table.<br />
The following mapping table lists how <strong>SAP</strong> <strong>HANA</strong> SQL types are mapped to OData EDM types during the<br />
activation of an OData service definition.<br />
Note: The OData implementation in <strong>SAP</strong> <strong>HANA</strong> XS supports only those SQL types listed in the following<br />
table.<br />
Table 8: <strong>SAP</strong> <strong>HANA</strong> SQL to OData EDM Type Mapping<br />
<strong>SAP</strong> <strong>HANA</strong> SQL Type OData EDM Type<br />
Time Edm.Time<br />
Date Edm.DateTime<br />
186<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
<strong>SAP</strong> <strong>HANA</strong> SQL Type OData EDM Type<br />
SecondDate Edm.DateTime<br />
LongDate Edm.DateTime<br />
Timestamp Edm.DateTime<br />
TinyInt Edm.Byte<br />
SmallInt Edm.Int16<br />
Integer Edm.Int32<br />
BigInt Edm.Int64<br />
SmallDecimal Edm.Decimal<br />
Decimal Edm.Decimal<br />
Real Edm.Single<br />
Float Edm.Single<br />
Double Edm.Double<br />
Varchar Edm.String<br />
NVarchar Edm.String<br />
Char Edm.String<br />
NChar Edm.String<br />
Binary Edm.Binary<br />
Varbinary Edm.Binary<br />
Example SQL Type Mapping<br />
The following examples shows how <strong>SAP</strong> <strong>HANA</strong> SQL types (name, integer, Varchar) of columns in a table are<br />
mapped to the OData EDM types in the properties of an entity type.<br />
<strong>SAP</strong> <strong>HANA</strong> SQL:<br />
{name = "ID"; sqlType = INTEGER; nullable = false;},<br />
{name = "RefereeID"; sqlType = VARCHAR; nullable = true;}<br />
The following example illustrates how the <strong>SAP</strong> <strong>HANA</strong> SQL types illustrated in the previous example are mapped to<br />
EDM types:<br />
<br />
<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 187
8.1.9 OData Service-Definition Examples<br />
The OData service definition describes how data exposed in an end point can be accessed by clients using the<br />
OData protocol.<br />
Each of the examples listed below is explained in a separate section. The examples show how to use the OData<br />
Service Definition Language (OSDL) in the OData service-definition file to generate an operational OData service<br />
that enables clients to use <strong>SAP</strong> <strong>HANA</strong> XS to access the OData end point you set up.<br />
● Empty Service<br />
● Namespace Definition<br />
● Object Exposure<br />
● Property Projection<br />
● Key Specification<br />
● Associations<br />
● Aggregation<br />
● Parameter Entity Sets<br />
OData Empty Service<br />
An OData service for <strong>SAP</strong> <strong>HANA</strong> XS is defined by a text file containing at least the following line:<br />
Service definition sample.odata:empty.xsodata<br />
service {}<br />
A service file with the minimal content generates an empty, completely operational OData service with an empty<br />
service catalog and an empty metadata file:<br />
http://localhost:8002/sample/odata/empty.xsodata<br />
http://localhost:8002/sample/odata/empty.xsodata/$metadata<br />
188<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
An empty service metadata document consists of one Schema containing an empty EntityContainer. The<br />
name of the EntityContainer is the name of the .xsodata file, in this example "empty".<br />
OData Namespace Definition<br />
By default, as shown in the metadata file of an empty OData service, the namespace of the generated Schema is<br />
created by concatenating the package name of the .xsodata file with the file name, and separating the<br />
concatenated names with a dot. You can specify your own namespace by using the namespace keyword:<br />
Service definition sample.odata:namespace.xsodata<br />
service namespace "my.namespace" {}<br />
The resulting service metadata document has the specified schema namespace:<br />
http://localhost:8002/sample/odata/namespace.xsodata/$metadata<br />
OData Object Exposure<br />
There are two ways of exposing <strong>SAP</strong> <strong>HANA</strong> objects. You can either specify the repository design-time name or the<br />
database-object runtime name (with database schema). Although both variants are supported, the preferred<br />
method is the exposure via the repository design-time name. It has the advantage that the OData service is<br />
automatically updated, if the underlying repository object changes. The support for database objects is mainly<br />
intended for existing or replicated objects that do not have a related repository design-time object.<br />
In the examples provided to illustrate object exposure, the following definition of a table applies:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 189
Table definition sample.odata:table.hdbtable<br />
table.schemaName = "ODATASAMPLES";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "ID"; sqlType = INTEGER;},<br />
{name = "Text"; sqlType = NVARCHAR; length=1000;},<br />
{name = "Time"; sqlType = TIMESTAMP;}<br />
];<br />
table.primaryKey.pkcolumns = ["ID"];<br />
Repository Objects<br />
If the object to expose via an OData service is created during an activation in the repository, then it has a<br />
repository design-time representation. Examples for those objects are tables, SQL views and calculation views. An<br />
example for exposing the table above is shown in the next listing.<br />
Service definition sample.odata:repo.xsodata<br />
service {<br />
"sample.odata:table.hdbtable" as "MyTable";<br />
}<br />
This service definition exposes a table defined in the .hdbtable file sample.odata:table.hdbtable and<br />
creates an EntitySet for this entity named "MyTable". The specification of an alias is optional. If omitted the<br />
default name of the EntitySet is the name of the repository object file, here "table".<br />
http://localhost:8002/sample/odata/repo.xsodata<br />
http://localhost:8002/sample/odata/repo.xsodata/$metadata<br />
190<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
All information about the table, for example, the properties, the data types, and the primary key, is gathered from<br />
the database catalog.<br />
Database Objects<br />
Caution: Do not use catalog objects if a repository design-time object is available, as changes in the<br />
catalog object are not automatically reflected in the OData service.<br />
Similar to the exposure of an object by using the repository design-time name is the exposure by the database<br />
name:<br />
Service definition sample.odata:db.xsodata<br />
service {<br />
"ODATASAMPLES"."sample.odata:table.hdbtable" as "MyTable";<br />
}<br />
The service exposes the same table by using the database catalog name of the object and the name of the<br />
schema where the table is created in. The collection in the service catalog and the EntityType that is created in the<br />
metadata document is exactly the same as for repository objects.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 191
OData Property Projection<br />
If the object you want to expose with an OData service has more columns than you actually want to expose, you<br />
can use SQL views to restrict the number of selected columns in the SELECT.<br />
Nevertheless, SQL views are sometimes not appropriate, for example with calculation views, and for these cases<br />
we provide the possibility to restrict the properties in the OData service definition in two ways. By providing an<br />
including or an excluding list of columns.<br />
Including Properties<br />
You can specify the columns of an object that have to be exposed in the OData service by using the with keyword.<br />
Key fields of tables must not be omitted.<br />
Service definition sample.odata:with.xsodata<br />
service {<br />
"sample.odata:table.hdbtable" as "MyTable" with ("ID","Text");<br />
}<br />
The resulting EntityType then contains only the properties derived from the specified columns:<br />
http://localhost:8002/sample/odata/with.xsodata/$metadata<br />
Excluding Properties<br />
The opposite of the with keyword is the without keyword, which enables you to specify which columns you do<br />
NOT want to expose in the OData service:<br />
Service definition sample.odata::without.xsodata<br />
service {<br />
"sample.odata:table.hdbtable" as "MyTable" without ("Text","Time");<br />
}<br />
The generated EntityType then does NOT contain the properties derived from the specified columns:<br />
http://localhost:8002/sample/odata/without.xsodata/$metadata<br />
192<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
OData Key Specification<br />
The OData specification requires an EntityType to denote a set properties forming a unique key. In <strong>HANA</strong> only<br />
tables may have a unique key, the primary key. For all other (mostly view) objects you need to specify a key for the<br />
entity. In OSDL you can do this by denoting a set of existing columns or by generating a key.<br />
For the examples illustrating key specification, we use the following SQL view, which selects all data from the<br />
specified table.<br />
View definition sample.odata:view.hdbview<br />
{<br />
}<br />
"name": "view",<br />
"schema": "ODATASAMPLES",<br />
"query": "SELECT * FROM \"ODATASAMPLES\".\"sample.odata::table\""<br />
Existing Key Properties<br />
If the object has set of columns that may form a unique key, you can specify them as key for the entity. These key<br />
properties are always selected from the database, no matter if they are omitted in the $select query option.<br />
Therefore explicit keys are not suitable for calculation views and analytic views as the selection has an impact on<br />
the result.<br />
Service definition sample.odata:explicitkeys.xsodata/$metadata<br />
service {<br />
"sample.odata:view.hdbview" as "MyView" keys ("ID","Text");<br />
}<br />
The created metadata document for the exposure of the view above is almost equal to the metadata document for<br />
repository objects. Only the key is different and consists now of two columns:<br />
http://localhost:8002/sample/odata/explicitkeys.xsodata/$metadata<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 193
Caution: The OData infrastructure cannot check whether your specified keys are unique. So be careful<br />
when choosing keys.<br />
Generated Local Key<br />
For objects that do not have a unique key in their results, for example, calculation views or aggregated tables, you<br />
can generate a locally valid key. This key value numbers the results starting with 1 and is not meant for<br />
dereferencing the entity; you cannot use this key to retrieve the entity. The key is valid only for the duration of the<br />
current session and is used only to satisfy OData's need for a unique ID in the results. The property type of a<br />
generated local key is Edm.String and cannot be changed.<br />
Service definition sample.odata:generatedkeys.xsodata<br />
http://localhost:8002/sample/odata/generatedkeys.xsodata/$metadata<br />
194<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
As a consequence of the transient nature of generated local keys, it is not possible to define navigation properties<br />
on these entities or use them in filter or order by conditions.<br />
OData Associations<br />
You can define associations between entities to express relationships between entities. With associations it is<br />
possible to reflect foreign key constraints on database tables, hierarchies and other relations between database<br />
objects. OSDL supports simple associations, where the information about the relationship is stored in one of the<br />
participating entities, and complex associations, where the relationship information is stored in a separate<br />
association table.<br />
Associations themselves are freestanding. On top of them you can specify which of the entities participating in the<br />
relationship can navigate over the association to the other entity by creating NavigationPropertys.<br />
For the examples used to illustrate OData associations, we use the tables customer and order:<br />
Table definition: sample.odata:customer.hdbtable<br />
table.schemaName = "ODATASAMPLES";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "ID"; sqlType = INTEGER; nullable = false;},<br />
{name = "RecruitID"; sqlType = VARCHAR; nullable = true;}<br />
];<br />
table.primaryKey.pkcolumns = ["ID"];<br />
Table definition: sample.odata:order.hdbtable<br />
table.schemaName = "ODATASAMPLES";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "ID"; sqlType = INTEGER; nullable = false;},<br />
{name = "CustomerID"; sqlType = INTEGER; nullable = false;}<br />
];<br />
table.primaryKey.pkcolumns = ["ID"];<br />
There is one relationship order.CustomerID to customer.ID and one relationship<br />
customer.RecruitID to customer.ID.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 195
Simple Associations<br />
The definition of an association requires you to specify a name, which references two exposed entities and whose<br />
columns keep the relationship information. To distinguish the ends of the association, you must use the keywords<br />
principal and dependent. In addition, it is necessary to denote the multiplicity for each end of the<br />
association.<br />
Service definition: sample.odata:assocsimple.xsodata<br />
service {<br />
"sample.odata:customer.hdbtable" as "Customers";<br />
"sample.odata:order.hdbtable" as "Orders";<br />
association "Customer_Orders" principal "Customers"("ID") multiplicity<br />
"1" dependent "Orders"("CustomerID") multiplicity "*";<br />
}<br />
The association in the example above with the name Customer_Orders defines a relationship between the<br />
table customer, identified by its EntitySet name Customers, on the principal end, and the table<br />
order, identified by its entity set name Orders, on the dependent end. Involved columns of both tables are<br />
denoted in braces ({}) after the name of the corresponding entity set. The multiplicity keyword on each end<br />
of the association specifies their cardinality - in this example, one-to-many.<br />
The number of columns involved in the relationship must be equal for both ends of the association, and their order<br />
in the list is important. The order specifies which column in one table is compared to which column in the other<br />
table. In this simple example, the column customer.ID is compared to order.CustomerID in the generated<br />
table join.<br />
As a result of the generation of the service definition above, an AssociationSet named Customer_Orders<br />
and an Association with name Customer_OrdersType are generated:<br />
http://localhost:8002/sample/odata/assocsimple.xsodata/$metadata<br />
196<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
The second association is similar to the first one and is shown in the following listing:<br />
association "Customer_Recruit" principal "Customers"("ID") multiplicity<br />
"1" dependent "Customers"("RecruitID") multiplicity "*";<br />
Complex Associations<br />
For the following example of a complex association, an additional table named knows is introduced that contains a<br />
relationship between customers.<br />
Table definition: sample.odata:knows.hdbtable<br />
table.schemaName = "ODATASAMPLES";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "KnowingCustomerID"; sqlType = INTEGER; nullable = false;},<br />
{name = "KnownCustomerID"; sqlType = INTEGER; nullable = false;}<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 197
];<br />
table.primaryKey.pkcolumns = ["KnowingCustomerID","KnownCustomerID"];<br />
Relationships that are stored in association tables such as knows can be similarly defined as simple associations.<br />
Use the keyword over to specify the additional table and any required columns.<br />
Service definition: sample.odata:assoccomplex.xsodata<br />
service {<br />
"sample.odata:customer.hdbtable" as "Customers";<br />
"sample.odata:order.hdbtable" as "Orders";<br />
association "Customer_Orders"<br />
principal "Customers"("ID") multiplicity "*"<br />
dependent "Customers"("ID") multiplicity "*"<br />
over "sample.odata:knows.hdbtable" principal ("KnowingCustomerID")<br />
dependent ("KnownCustomerID");<br />
}<br />
With the keywords principal and dependent after over you can specify which columns from the<br />
association table are joined with the principal respectively dependent columns of the related entities. The<br />
number of columns must be equal in pairs, and their order in the list is important.<br />
The generated Association in the metadata document is similar to the one created for a simple association<br />
except that the ReferentialConstraint is missing:<br />
tp://localhost:8002/sample/odata/assoccomplex.xsodata/$metadata<br />
Navigation Properties<br />
By only defining an association, it is not possible to navigate from one entity to another. Associations need to be<br />
bound to entities by an NavigationProperty. You can create them by using the keyword navigates:<br />
Service definition: sample.odata:assocnav.xsodata<br />
service {<br />
"sample.odata:customer.hdbtable" as "Customers" navigates<br />
("Customer_Orders" as "HisOrders");<br />
"sample.odata:order.hdbtable" as "Orders";<br />
association "Customer_Orders" principal "Customers"("ID") multiplicity<br />
198<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
"1" dependent "Orders"("CustomerID") multiplicity "*";<br />
}<br />
The example above says that it is possible to navigate from Customers over the association<br />
Customer_Order via the NavigationProperty named "HisOrders".<br />
The right association end is determined automatically by the entity set name. But if both ends are bound to the<br />
same entity, it is necessary to specify the starting end for the navigation. This is done by specifying either from<br />
principal or from dependent which refer to the principal and dependent ends in the association.<br />
Service definition: sample.odata:assocnavself.xsodata<br />
service {<br />
"sample.odata:customer.hdbtable" as "Customers"<br />
navigates ("Customer_Orders" as "HisOrders","Customer_Recruit" as<br />
"Recruit" from principal);<br />
"sample.odata:order.hdbtable" as "Orders";<br />
association "Customer_Orders" principal "Customers"("ID") multiplicity<br />
"1" dependent "Orders"("CustomerID") multiplicity "*";<br />
association "Customer_Recruit" principal "Customers"("ID")<br />
multiplicity "1" dependent "Customers"("RecruitID") multiplicity "*";<br />
}<br />
In both cases a NavigationProperty is added to the EntityType.<br />
http://localhost:8002/sample/odata/assocnavself.xsodata/$metadata<br />
OData Aggregation<br />
The results of aggregations on columns change dynamically depending on the grouping conditions. This means<br />
that aggregation cannot be performed in SQL views; it needs to be specified in the OData service definition itself.<br />
Depending on the type of object to expose, you need to explicitly specify the columns to aggregate and the<br />
function to use or derived them from metadata in the database.<br />
In general, aggregations do not have consequences for the metadata document. It just effects the semantics of<br />
the concerning properties during runtime. The grouping condition for the aggregation contain all selected nonaggregated<br />
properties. Furthermore, aggregated columns cannot be used in $filter, and aggregation is only<br />
possible with generated keys.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 199
Derived Aggregation<br />
The simplest way to define aggregations of columns in an object is to derive this information from metadata in the<br />
database. The only objects with this information are calculation views and analytic views. For all other object<br />
types, for example, tables and SQL views, the activation will not work. To cause the service to use derived<br />
information, you must specify the keywords aggregates always, as illustrated in the following example:<br />
service {<br />
"sample.odata:calc.calculationview" as "CalcView"<br />
keys generate local "ID"<br />
aggregates always;<br />
}<br />
Explicit Aggregation<br />
The example for the explicit aggregation is based on the following table definition:<br />
sample.odata:revenues.hdbtable<br />
table.schemaName = "ODATASAMPLES";<br />
table.tableType = COLUMNSTORE;<br />
table.columns = [<br />
{name = "Month"; sqlType = INTEGER; nullable = false;},<br />
{name = "Year"; sqlType = INTEGER; nullable = false;},<br />
{name = "Amount"; sqlType = INTEGER; nullable = true;}<br />
];<br />
table.primaryKey.pkcolumns = ["Month","Year"];<br />
You can aggregate the columns of objects (without metadata) that are necessary for the derivation of aggregation<br />
by explicitly denoting the column names and the functions to use, as illustrated in the following example of a<br />
service definition: sample.odata:aggrexpl.xsodata<br />
service {<br />
"sample.odata:revenues.hdbtable" as "Revenues"<br />
keys generate local "ID"<br />
aggregates always (SUM of "Amount");<br />
}<br />
The results of the entity set Revenues always contain the aggregated value of the column Amount. To extract<br />
the aggregated revenue amount per year, add $select=Year,Amount to your requested URI.<br />
OData Parameter Entity Sets<br />
<strong>SAP</strong> <strong>HANA</strong> calculation views and analytic views can interpret input parameters. For OData, these parameters can<br />
be entered by using a special parameter entity set.<br />
Parameter entity sets can be generated for both calculation views and analytic views by adding parameters via<br />
entity to the entity:<br />
service {<br />
"sample.odata:calc.calculationview" as "CalcView"<br />
keys generate local "ID"<br />
200<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
}<br />
parameters via entity;<br />
During activation, the parameters specified in sample.odata:calc.calculationview are retrieved from<br />
the metadata of the calculation view and exposed as a new EntitySet named after the entity set name and the<br />
suffix Parameters, for example, CalcViewParameters. A NavigationProperty named Results is<br />
generated to retrieve the results from the parameterized call.<br />
The name of the generated parameter entity set and the navigation property can be customized, as illustrated in<br />
the following example:<br />
service {<br />
"sample.odata:calc.calculationview" as "CalcView"<br />
keys generate local "ID"<br />
parameters via entity "CVParams" results property "Execute";<br />
}<br />
With the definition above, the name of the parameter entity set is CVParams, and the name of the<br />
NavigationProperty for the results is Execute.<br />
8.2 Data Access with XMLA in <strong>SAP</strong> <strong>HANA</strong> XS<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services, the persistence model (for example, tables, views and stored<br />
procedures) is mapped to the consumption model that is exposed to clients - the applications you write to extract<br />
data from the <strong>SAP</strong> <strong>HANA</strong> database.<br />
You can map the persistence and consumption models with XML for Analysis (XMLA). With XMLA, you write<br />
multi-dimensional -expressions (MDX) queries wrapped in an XMLA document. An XML for Analysis (XMLA)<br />
application running in <strong>SAP</strong> <strong>HANA</strong> application services is used to provide the consumption model for client<br />
applications exchanging MDX queries (wrapped in XMLA documents) with the <strong>SAP</strong> <strong>HANA</strong> database.<br />
XMLA uses Web-based services to enable platform-independent access to XMLA-compliant data sources for<br />
Online Analytical Processing (OLAP). XMLA enables the exchange of analytical data between a client application<br />
and a multi-dimensional data provider working over the Web, using a Simple Object Access Protocol (SOAP)based<br />
XML communication application-programming interface (API).<br />
Applications running in <strong>SAP</strong> <strong>HANA</strong> XS enable very accurate control of the flow of data between the presentational<br />
layer, for example, in the Browser, and the data-processing layer in <strong>SAP</strong> <strong>HANA</strong> itself, where the calculations are<br />
performed, for example in SQL or SqlScript. If you develop and deploy an XMLA service running in <strong>SAP</strong> <strong>HANA</strong> XS,<br />
you can take advantage of the embedded access to <strong>SAP</strong> <strong>HANA</strong> that <strong>SAP</strong> <strong>HANA</strong> XS provides; the embedded<br />
access greatly improves end-to-end performance.<br />
8.2.1 XML for Analysis (XMLA)<br />
XML for Analysis (XMLA) uses Web-based services to enable platform-independent access to XMLA-compliant<br />
data sources for Online Analytical Processing (OLAP).<br />
XMLA enables the exchange of analytical data between a client application and a multi-dimensional data provider<br />
working over the Web, using a Simple Object Access Protocol (SOAP)-based XML communication applicationprogramming<br />
interface (API).<br />
Implementing XMLA in <strong>SAP</strong> <strong>HANA</strong> enables third-party reporting tools that are connected to the <strong>SAP</strong> <strong>HANA</strong><br />
database to communicate directly with the MDX interface. The XMLA API provides universal data access to a<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 201
particular source over the Internet, without the client having to set up a special component. XML for Analysis is<br />
optimized for the Internet in the following ways:<br />
● Query performance<br />
Time spent on queries to the server is kept to a minimum<br />
● Query type<br />
Client queries are stateless by default; after the client has received the requested data, the client is<br />
disconnected from the Web server.<br />
In this way, tolerance to errors and the scalability of a source (the maximum permitted number of users) is<br />
maximized.<br />
XMLA Methods<br />
The specification defined in XML for Analysis Version 1.1 from Microsoft forms the basis for the implementation of<br />
XML for Analysis in <strong>SAP</strong> <strong>HANA</strong>.<br />
The following list describes the methods that determine the specification for a stateless data request and<br />
provides a brief explanation of the method's scope:<br />
● Discover<br />
Use this method to query metadata and master data; the result of the discover method is a rowset. You can<br />
specify options, for example, to define the query type, any data-filtering restrictions, and any required XMLA<br />
properties for data formatting.<br />
● Execute<br />
Use this method to execute MDX commands and receive the corresponding result set; the result of the<br />
Execute command could be a mult-idimensional dataset or a tabular rowset. You can set options to specify<br />
any required XMLA properties, for example, to define the format of the returned result set or any local<br />
properties to use to determine how to format the returned data.<br />
8.2.2 XMLA Service Definition<br />
The XMLA service definition is a file you use to specify which data is exposed as XMLA collections. Exposed data is<br />
available for analysis and display by client applications, for example, a browser that uses functions provided either<br />
by the XMLA service running in <strong>SAP</strong> <strong>HANA</strong> XS or by an XMLA client library running on the client system.<br />
To expose information via XMLA to applications using <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS),<br />
you define database views that provide the data with the required granularity and you use the XMLA service<br />
definition to control access to the exposed data.<br />
Note: <strong>SAP</strong> <strong>HANA</strong> XS supports XMLA version 1.1, which you can use to send MDX queries.<br />
An XMLA service for <strong>SAP</strong> <strong>HANA</strong> XS is defined in a text file with the file suffix .xsxmla, for example,<br />
XMLASrvDef.xsxmla. The file must contain only the entry {*}, which would generate a completely<br />
operational XMLA service.<br />
202<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
XMLA Service-Definition Keywords<br />
Currently, the XMLA service-definition file enables you to specify only that all authorized data is exposed to XMLA<br />
requests, as illustrated in the following example:<br />
Service {*}<br />
8.2.3 XMLA Security Considerations<br />
Enabling access to data by means of XMLA opens up some security considerations that you need to address, for<br />
example, the data you want to expose, who can start the XMLA service, and so on.<br />
If you want to use XMLA to expose data to users and clients in <strong>SAP</strong> <strong>HANA</strong> XS, you need to bear in mind the<br />
security considerations described in the following list:<br />
● Data Access<br />
●<br />
Restrict user select authorization for data exposed by the XMLA service<br />
● XMLA Statistical content<br />
Restrict access to the URL/Path used to expose XMLA content in the Web browser, for example, using the<br />
application-access file (.xsaccess)<br />
8.2.4 Multidimensional Expressions (MDX)<br />
Multidimensional Expressions (MDX) is a language you can use to query multidimensional data stored in OLAP<br />
cubes.<br />
MDX uses a multidimensional data model to enable navigation in multiple dimensions, levels, and up and down a<br />
hierarchy. With MDX, you can access pre-computed aggregates at specified positions (levels or members) in a<br />
hierarchy.<br />
Note: MDX is an open standard. However, <strong>SAP</strong> has developed extensions to MDX that are designed to<br />
enable faster and more efficient access to multidimensional data, for example, to serve specific <strong>SAP</strong><br />
<strong>HANA</strong> application requirements and to optimize the resultset for <strong>SAP</strong> <strong>HANA</strong> clients.<br />
MDX is implicitly a hierarchy-based paradigm. All members of all dimensions must belong to a hierarchy. Even if<br />
you do not explicitly create hierarchies in your <strong>SAP</strong> <strong>HANA</strong> data model, the <strong>SAP</strong> <strong>HANA</strong> modeler implicitly<br />
generates default hierarchies for each dimension. All identifiers that are used to uniquely identify hierarchies,<br />
levels and members in MDX statements (and metadata requests) embed the hierarchy name within the identifier.<br />
In <strong>SAP</strong> <strong>HANA</strong>, the standard use of MDX is to access <strong>SAP</strong> <strong>HANA</strong> models (for example, analytical and attribute<br />
views) that have been designed, validated and activated in the modeler in the <strong>SAP</strong> <strong>HANA</strong> studio. The studio<br />
provides a graphical design environment that enables detailed control over all aspects of the model and its<br />
language-context-sensitive runtime representation to users.<br />
MDX in <strong>SAP</strong> <strong>HANA</strong> uses a runtime cube model, which usually consists of an analytical (or calculation) view that<br />
represents data in which dimensions are modeled as attribute views. You can use the analytical view to specify<br />
whether a given attribute is intended for display purposes only or for aggregation. The key attributes of attribute<br />
views are linked to private attributes in an analytical view in order to connect the entities. One benefit of MDX in<br />
<strong>SAP</strong> <strong>HANA</strong> is the native support of hierarchies defined for attribute views.<br />
Note: MDX in <strong>SAP</strong> <strong>HANA</strong> includes native support of hierarchies defined for attribute views. <strong>SAP</strong> <strong>HANA</strong><br />
supports level-based and parent-child hierarchies and both types of hierarchies are accessible with MDX.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 203
<strong>SAP</strong> <strong>HANA</strong> supports the use of variables in MDX queries; the variables are a <strong>SAP</strong>-specific enhancement to<br />
standard MDX syntax. You can specify values for all mandatory variables that are defined in <strong>SAP</strong> <strong>HANA</strong> studio to<br />
various modeling entities. The following example illustrates how to declare <strong>SAP</strong> <strong>HANA</strong> variables and their values:<br />
MDX<br />
Select<br />
From [MINI_C1_VAR]<br />
Where [Measures].[M2_1_M3_CONV]<br />
<strong>SAP</strong> VARIABLES [VAR_VAT] including 10,<br />
[VAR_K2] including 112,<br />
[VAR_TARGET_CURRENCY] including 'EUR',<br />
8.2.5 MDX Functions<br />
MDX in <strong>SAP</strong> <strong>HANA</strong> supports a variety of standard MDX functions.<br />
Table 9: Supported MDX Functions<br />
Function Description<br />
Aggregate Returns a calculated value using the appropriate aggregate function, based on the<br />
aggregation type of the member.<br />
Ancestor Returns the ancestor of a member at a specified level or at a specific distance away<br />
in the hierarchy.<br />
Ancestors Returns a set of all ancestors of a member at a specified level or at a specific<br />
distance away in the hierarchy.<br />
Ascendants Returns the set of the ascendants of the member.<br />
Avg Returns the average value of a numeric expression evaluated over a set.<br />
BottomCount Returns a specified number of items from the bottom of a set, optionally sorting<br />
the set first.<br />
Children Returns the children of a member.<br />
ClosingPeriod Returns the last sibling among the descendants of a member at a specified level.<br />
Count Counts the number of members in the tuple.<br />
Cousin Returns the child member with the same relative position under a parent member<br />
as the specified child member.<br />
Crossjoin Returns the cross product of two sets.<br />
CurrentMember Returns the current member along a hierarchy.<br />
DefaultMember Returns the default member of a hierarchy.<br />
Descendants Returns the set of descendants of a member at a specified level or at a specific<br />
distance away in the hierarchy.<br />
Dimension Returns the hierarchy that contains a specified member or level.<br />
Dimensions Returns a hierarchy specified by a numeric or string expression.<br />
Distinct Returns a set, removing duplicate tuples from a specified set.<br />
DistinctCount Returns the number of distinct tuples in a set.<br />
204<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
Function Description<br />
DrillDownLevel Drills down the members of a set one level below the lowest level represented in the<br />
set, or to one level below an optional level of a member represented in the set.<br />
DrillDownLevelBottom Drills down the members of a specified count of bottom members of a set, at a<br />
specified level, to one level below.<br />
DrillDownLevelTop Drills down a specified count of top members of a set, at a specified level, to one<br />
level below.<br />
DrillDownMember Drills down the members in a specified set that are present in a second specified<br />
set.<br />
DrillDownMemberBottom Drills down the members in a specified set that are present in a second specified<br />
set, limiting the result set to a specified number of bottommost members.<br />
DrillDownMemberTop Drills down the members in a specified set that are present in a second specified<br />
set, limiting the result set to a specified number of topmost members.<br />
DrillUpLevel Drills up the members of a set that are below a specified level.<br />
DrillUpmember Drills up the members in a specified set that are present in a second specified set.<br />
Except Finds the difference between two sets, optionally retaining duplicates.<br />
Filter Returns the set resulting from filtering a set based on a search condition.<br />
FirstChild Returns the first child of a specified member.<br />
FirstSibling Returns the first child of the parent of a specified member.<br />
Generate Applies a set to each member of another set, and then joins the resulting sets by<br />
union. Alternatively, this function returns a concatenated string created by<br />
evaluating a string expression over a set.<br />
Head Returns the first specified number of elements in a set.<br />
Hierarchize Orders the members of a specified set in a hierarchy in natural or, optionally, postnatural<br />
order.<br />
Hierarchy<br />
Instr The InStr function finds the starting location of a substring within a specified string.<br />
Intersect Returns the intersection of two sets, optionally retaining duplicates.<br />
IsAncestor Returns true if the first member specified is an ancestor of the second member<br />
specified, else returns false.<br />
IsGeneration Returns true if the member specified is a leaf, else returns false.<br />
IsLeaf Returns true if the first member specified is an ancestor of the second member<br />
specified, else returns false.<br />
IsSibling Returns true if the first member specified is an sibling of the second member<br />
specified, else returns false.<br />
Item If an integer is specified, the Item function returns the tuple that is in the zerobased<br />
position specified by Index.<br />
IIF Returns one of values determined by a logical test.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 205
Function Description<br />
Lag Returns the member that is a specified number of positions prior to a specified<br />
member along the dimension of the member.<br />
LastChild Returns the last child of a specified member.<br />
LastPeriods Returns a set of members prior to and including a specified member.<br />
LastSibling Returns the last child of the parent of a specified member.<br />
Lead Returns the member that is a specified number of positions following a specified<br />
member along the dimension of the member.<br />
Leaves If a dimension name is specified, returns a set that contains the leaf members of<br />
the key attribute for the specified dimension.If a dimension name is not specified,<br />
the function returns a set that contains the leaf members of the entire cube.<br />
Left The Left function returns a string of a specified number of characters from the left<br />
side (beginning) of a specified string.<br />
Level Returns the level of a member.<br />
Levels Returns the level whose zero-based position in a dimension is specified by a<br />
numeric expression.<br />
Max Returns the maximum value of a numeric expression evaluated over a set.<br />
Member_caption Returns the caption of a member<br />
Members Returns the set of all members in a specified hierarchy.<br />
MembersAscendantsDesc<br />
endants<br />
Returns the set of specified members in a given hierarchy.<br />
Mid The Mid function returns a substring of a string argument.<br />
Min Returns the minimum value of a numeric expression evaluated over a set<br />
MTD Returns a set of members from the Month level in a Time dimension starting with<br />
the first period and ending with a specified member.<br />
Name Returns the name of a specified hierarchy or member.<br />
NextMember Returns the next member in the level that contains a specified member.<br />
NOT Performs a logical negation on a numeric expression.<br />
OpeningPeriod Returns the first sibling among the descendants of a specified level, optionally at a<br />
specified member.<br />
OR Performs a logical disjunction on two numeric expressions.<br />
Ordinal Returns the zero-based ordinal value associated with a specified level.<br />
ParallelPeriod Returns a member from a prior period in the same relative position as a specified<br />
member.<br />
Parent Returns the parent of a specified member.<br />
PeriodsToDate Returns a set of members (periods) from a specified level starting with the first<br />
member and ending with a specified member.<br />
206<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
Function Description<br />
PrevMember Returns the previous member in the level that contains a specified member.<br />
Properties Returns a string containing the value of the specified member property.<br />
QTD Returns a set of members from the Quarter level in a Time dimension starting with<br />
the first period and ending with a specified member.<br />
Range Performs a set operation that returns a naturally ordered set, with the two<br />
specified members as endpoints, and all members between the two specified<br />
members included as members of the set<br />
Right The Right function returns a string of a specified number of characters from the<br />
right side (end) of a specified string.<br />
Siblings Returns the set of siblings of a specified member, including the member itself.<br />
StrToMember Returns a member from a string expression in MDX format.<br />
StrToSet Constructs a set from a specified string expression in MDX format.<br />
StrToTuple Constructs a tuple from a specified string expression in MDX format.<br />
StrToValue Returns a value from a string expression<br />
Subset Returns a subset of tuples from a specified set.<br />
Sum Returns the sum of a numeric expression evaluated over a specified set.<br />
Tail Returns the last specified number of elements in a set.<br />
TopCount Returns a specified number of items from the topmost members of a specified set,<br />
optionally ordering the set first.<br />
Union Performs a set operation that returns a union of two sets, removing duplicate<br />
members.<br />
UniqueName Returns the unique name of a specified hierarchy.<br />
WTD Returns a set of members from the Week level in a Time dimension starting with<br />
the first period and ending with a specified member.<br />
YTD Returns a set of members from the Year level in a Time dimension starting with the<br />
first period and ending with a specified member.<br />
8.2.6 MDX Extensions<br />
<strong>SAP</strong> <strong>HANA</strong> supports several extensions to the MDX language, for example, additional predefined functions and<br />
support for variables.<br />
Sibling_Ordinal Intrinsic Property<br />
The object Member includes a property called Sibling_Ordinal, that is equal to the 0-based position of the<br />
member within its siblings.<br />
WITH<br />
MEMBER [Measures].[Termination Rate] AS<br />
[Measures].[NET_SALES] / [Measures].[BILLED_QUANTITY]<br />
SELECT<br />
{<br />
[Measures].[NET_SALES],<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 207
[Measures].[BILLED_QUANTITY],<br />
[Measures].[Termination Rate]<br />
} ON COLUMNS,<br />
Descendants<br />
(<br />
[MDX_TEST_10_DISTRIBUTION_CHANNEL].<br />
[MDX_TEST_10_DISTRIBUTION_CHANNEL].[All].[(all)],<br />
1,<br />
SELF_AND_BEFORE<br />
)<br />
DIMENSION PROPERTIES SIBLING_ORDINAL ON ROWS<br />
FROM MDX_TEST_10_ITELO_SALES_DATA<br />
MembersAscendantsDescendants Function<br />
<strong>SAP</strong> <strong>HANA</strong> includes a new function called MembersAscendantsDescendants that enables you to get, for<br />
example, all ascendants and descendants of a specific member. This function improves on the standard MDX<br />
functions Ascendants and Descendants.<br />
The function can be called as follows:<br />
MembersAscendantsDescendants (, )<br />
● set: A set of members from a single hierarchy<br />
● flag: Indicates which related members to return, and can be one of the following:<br />
○ MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS<br />
○ MEMBERS_AND_ASCENDANTS<br />
○ MEMBERS_AND_DESCENDANTS<br />
○ ASCENDANTS_AND_DESCENDANTS<br />
○ ONLY_ASCENDANTS<br />
○ ONLY_DESCENDANTS<br />
SELECT<br />
{ [Measures].[SALES] }<br />
ON COLUMNS,<br />
NON EMPTY<br />
{ Hierarchize( MembersAscendantsDescendants([JUICE_TIME].[TimeHier].<br />
[QUARTER].[3]:[JUICE_TIME].[TimeHier].[QUARTER].[4],<br />
MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS )) }<br />
ON ROWS<br />
FROM [JUICE]<br />
SELECT<br />
{ [Measures].[SALES] }<br />
ON COLUMNS,<br />
NON EMPTY<br />
{ Hierarchize( MembersAscendantsDescendants([JUICE_TIME].[TimeHier].<br />
[QUARTER].[3]:[JUICE_TIME].[TimeHier].[QUARTER].[4],<br />
ONLY_ASCENDANTS )) }<br />
ON ROWS<br />
FROM [JUICE]<br />
Variables<br />
An MDX SELECT statement in <strong>SAP</strong> <strong>HANA</strong> enables you to send values for variables defined within modeling views.<br />
208<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
Analytic and calculation views can contain variables, that can be bound to specific attributes. When calling the<br />
view, you can send values for those variables. These variables can be used, for example, to filter the results.<br />
<strong>SAP</strong> <strong>HANA</strong> supports an extension to MDX whereby you can pass values for variables defined in views by adding a<br />
<strong>SAP</strong> Variables clause in your select statement. Here is the syntax for a Select statement:<br />
: [WITH ]<br />
SELECT [[,...]]<br />
FROM <br />
[WHERE <br />
<strong>SAP</strong> VARIABLES: [[,] …]]<br />
: [] <br />
: INCLUDING | EXCLUDING<br />
: = | > | >= | < |
8.2.7 Defining the Data an XMLA Service Exposes<br />
An XMLA service exposes data stored in database tables for analysis and display by client applications. However,<br />
first of all, you need to ensure that the tables and views to expose as an XMLA service actually exist and are<br />
accessible.<br />
To define the data to expose using an XMLA service, you must perform at least the following tasks:<br />
1. Create a simple database schema.<br />
2. Create a simple database table to expose with an XMLA service.<br />
3. If required, create a simple database view to expose with an XMLA service.<br />
4. Grant select privileges to the tables and views to be exposed with the XMLA service.<br />
8.2.8 Creating an XMLA Service Definition<br />
The XMLA service definition is a file you use to specify which data is exposed as XMLA/MDX collections for<br />
analysis and display by client applications.<br />
An XMLA service for <strong>SAP</strong> <strong>HANA</strong> XS is defined in a text file with the file suffix .xsxmla, for example,<br />
XMLASrvDef.xsxmla. The file resides in the package hierarchy of the XMLA application and must contain the<br />
entry service {*}, which generates an operational XMLA service.<br />
Prerequisities for the creation of an XMLA service definition:<br />
● <strong>SAP</strong> <strong>HANA</strong> studio and client installed and configured<br />
● <strong>SAP</strong> <strong>HANA</strong> database user available with repository privileges (for example, to add packages)<br />
● A <strong>SAP</strong> <strong>HANA</strong> development system added to (and available in) <strong>SAP</strong> <strong>HANA</strong> studio, for example, in either the<br />
Navigator view or the <strong>SAP</strong> <strong>HANA</strong> Repositories view<br />
● A working development environment including a repository workspace, a package structure for your XMLA<br />
application, and a shared project to enable you to synchronize changes to the XMLA project files in the local<br />
file system with the repository<br />
● Data is available to expose using the XMLA interface<br />
1. In the shared project you are using for your XMLA application, use the Project Explorer view to locate the<br />
package where you want to create the new XMLA service definition.<br />
Note: The file containing the XMLA service definition must be placed in the root package of the XMLA<br />
application for which the service is intended.<br />
2. Create the file that will contain your XMLA service definition.<br />
In the Project Explorer view, right-click the folder where you want to create the new XMLA service-definition<br />
file and choose New File in the context-sensitive popup menu displayed.<br />
3. Create the XMLA service definition.<br />
210<br />
The XMLA service definition is a configuration file that you use to specify which data is to be exposed as an<br />
XMLA collection.<br />
The following code is an example of a valid XMLA service definition, which exposes all authorized data to<br />
XMLA requests:<br />
{*}<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access
4. Place the valid XMLA service definition in the root package of the XMLA application.<br />
5. Save, commit, and activate the XMLA service definition in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Defining Web-based Data Access<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 211
9 Writing Server-Side JavaScript<br />
Applications<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) provide applications and application developers with<br />
access to the <strong>SAP</strong> <strong>HANA</strong> database using a consumption model that is exposed via HTTP.<br />
In addition to providing application-specific consumption models, <strong>SAP</strong> <strong>HANA</strong> XS also host system services that<br />
are part of the <strong>SAP</strong> <strong>HANA</strong> database, for example: search services and a built-in Web server that provides access<br />
to static content stored in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
The consumption model provided by <strong>SAP</strong> <strong>HANA</strong> XS focuses on server-side applications written in JavaScript. The<br />
server-side JavaScript applications can make use of a powerful set of specially developed API functions, for<br />
example, to enable access to the current request session or the database. This section describes how to write a<br />
server-side JavaScript application that enables you to expose data, for example, using a Web Browser or any<br />
other HTTP client.<br />
9.1 Data Access with JavaScript in <strong>SAP</strong> <strong>HANA</strong> XS<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services, the persistence model (for example, tables, views and stored<br />
procedures) is mapped to the consumption model that is exposed via HTTP to clients - the applications you write<br />
to extract data from <strong>SAP</strong> <strong>HANA</strong>.<br />
You can map the persistence and consumption models in the following way:<br />
● Application-specific code<br />
Write code that runs in <strong>SAP</strong> <strong>HANA</strong> application services. Application-specific code (for example, server-side<br />
JavaScript) is used in <strong>SAP</strong> <strong>HANA</strong> application services to provide the consumption model for client<br />
applications.<br />
Applications running in <strong>SAP</strong> <strong>HANA</strong> XS enable you to accurately control the flow of data between the<br />
presentational layer, for example, in the Browser, and the data-processing layer in <strong>SAP</strong> <strong>HANA</strong> itself, where the<br />
calculations are performed, for example in SQL or SQLScript. If you develop and deploy a server-side JavaScript<br />
application running in <strong>SAP</strong> <strong>HANA</strong> XS, you can take advantage of the embedded access to <strong>SAP</strong> <strong>HANA</strong> that <strong>SAP</strong><br />
<strong>HANA</strong> XS provides; the embedded access greatly improves end-to-end performance.<br />
9.2 Writing JavaScript Code<br />
9.2.1 Server-Side JavaScript in <strong>SAP</strong> <strong>HANA</strong> XS<br />
<strong>SAP</strong> <strong>HANA</strong> application services (XS server) supports server-side application programming in JavaScript. The<br />
server-side application you develop can use a collection of JavaScript APIs to expose authorized data to client<br />
requests, for example, to be consumed by a client GUI such as a Web browser or any other HTTP client.<br />
212<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
The functions provided by the JavaScript APIs enable server-side JavaScript applications to perform the following<br />
actions:<br />
● Interact with the <strong>SAP</strong> <strong>HANA</strong> XS runtime environment<br />
● Directly access <strong>SAP</strong> <strong>HANA</strong> database capabilities<br />
Note: Unlike OData and XMLA, the JavaScript API enables you not only to expose data but to update,<br />
insert, and delete data, too.<br />
JavaScript programs are stored in the repository along with all the other development resources. When the<br />
programs are activated, the code is stored in the repository as a runtime object.<br />
9.2.2 JavaScript Editor<br />
You can write server-side JavaScript using the <strong>SAP</strong> <strong>HANA</strong> studio JavaScript editor, which provides syntax<br />
validation, code highlighting and code completion.<br />
When you edit a JavaScript file within an XS JavaScript project, the editor automatically has a reference to the XS<br />
JavaScript API. You can access the API’s objects by entering $, following by a period (.), and the objects are<br />
available, as in the following example.<br />
JSLint Validations<br />
The JavaScript editor includes the JSLint open-source library, which helps to validate JavaScript code. The editor<br />
highlights any code that does not conform to the JSLint standards.<br />
To configure the JSLint library and determine which validations are performed, go to:<br />
Windows Preferences JSLint<br />
In the preferences window, each JSLint setting is followed by the corresponding JSLint command name, which<br />
you can use to lookup more information on the JSLint Web site.<br />
Related Links<br />
JSLint Web Site<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 213
9.2.3 Server-Side JavaScript Security Considerations<br />
If you choose to use server-side JavaScript to write your application code, you need to bear in mind the potential<br />
for (and risk of) external attacks such as cross-site scripting and forgery, and insufficient authentication.<br />
The following list illustrates the areas where special attention is required to avoid security-related problems when<br />
writing server-side JavaScript. Each of the problems highlighted in the list is described in detail in its own section:<br />
● SSL/HTTPS<br />
● Injection flaws<br />
● Cross-site scripting (XSS)<br />
● Broken authentication and session management<br />
● Insecure direct object references<br />
● Cross-site request forgery<br />
● Incorrect security configuration<br />
● Insecure cryptographic storage<br />
● Missing restrictions on URL Access<br />
● Insufficient transport layer protection<br />
● Invalidated redirects and forwards<br />
● XML processing issues<br />
Inbound HTTPS/SSL Connections<br />
● Problem<br />
Incoming requests for data from client applications use secure HTTP (HTTPS), but the <strong>SAP</strong> <strong>HANA</strong> system is<br />
not configured to accept the HTTPS requests.<br />
● Solution<br />
Ensure the <strong>SAP</strong> Web Dispatcher is configured to accept incoming HTTPS requests. For more information, see<br />
the <strong>SAP</strong> <strong>HANA</strong> Administration <strong>Guide</strong>.<br />
Note: The HTTPS requests are forwarded internally from the <strong>SAP</strong> Web Dispatcher to <strong>SAP</strong> <strong>HANA</strong> XS as<br />
HTTP (clear text).<br />
Injection Flaws<br />
● Problem<br />
In the context of <strong>SAP</strong> <strong>HANA</strong> XS, injection flaws mostly concern SQL injection, which can occur in the <strong>SAP</strong><br />
<strong>HANA</strong> XS JavaScript API or SQL script itself (both standard and dynamic).<br />
● Solution<br />
214<br />
To prevent injection flaws in the JavaScript API, use prepared statements to create a query and place-holders<br />
to fill with results of function calls to the prepared-statement object; to prevent injection flaws in standard<br />
SQL Script, use stored procedures that run in caller mode; in caller mode, the stored procedures are<br />
executed with the credentials of the logged-on <strong>HANA</strong> user. Avoid using dynamic SQL if possible.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
Cross-site scripting (XSS)<br />
● Problem<br />
Cross-site scripting is a web-based vulnerability that involves an attacker injecting JavaScript into a link with<br />
the intention of running the injected code on the target computer; the vulnerability comes in two types:<br />
reflected (or non-persistent) and stored (or persistent). The "reflected" vulnerability affects individual users<br />
in their local Web browser; the "stored" vulnerability is stored on a server and affects all users who visit the<br />
served page.<br />
● Solution<br />
Since there are currently no libraries provided by the standard <strong>SAP</strong> <strong>HANA</strong> XS API to provide proper escaping,<br />
the best solution for generating HTML on <strong>SAP</strong> <strong>HANA</strong> XS is to use the E<strong>SAP</strong>I JavaScript libraries as a start<br />
point. In addition, we recommend not to write custom interfaces but to rely on well-tested technologies<br />
supplied by <strong>SAP</strong>, for example, OData or JSON together with <strong>SAP</strong>UI5 libraries.<br />
Broken authentication and session management<br />
● Problem<br />
Leaks or flaws in the authentication or session management functions allow attackers to impersonate users;<br />
the attackers can be external as well as users with their own accounts to get privileges of those users.<br />
● Solution<br />
Use the built-in <strong>SAP</strong> <strong>HANA</strong> XS authentication mechanism and session management (cookies). For example,<br />
use the "authentication" keyword to enable an authentication method and set it according to the<br />
authentication method you want implement, for example: <strong>SAP</strong> logon ticket, form-based, or basic (user name<br />
and password) in the application's .xsaccess file, which ensures that all objects in the application path are<br />
available only to authenticated users.<br />
Insecure direct object references<br />
● Problem<br />
An <strong>SAP</strong> <strong>HANA</strong> XS application is vulnerable to insecure direct object reference if the application lacks the<br />
proper authentication mechanism for target objects.<br />
● Solution<br />
Make sure that only authenticated users are allowed to access a particular object. In the context of <strong>SAP</strong> <strong>HANA</strong><br />
XS, use the "authentication" keyword to enable an authentication method and set it according to the<br />
authentication method you implement, for example: <strong>SAP</strong> logon ticket, form-based, or basic (user name and<br />
password) in the application's .xsaccess file, which ensures that all objects in the application path are<br />
available only to authenticated users.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 215
Cross-site request forgery<br />
● Problem<br />
Since there are no clear trust boundaries between different Web sites running in the same Web-browser<br />
session, an attacker can trick users (by sending an e-mail or luring them to a popular Web site that is under<br />
the attacker's control) into clicking a specific hyperlink. The hyperlink displays a Web site that performs<br />
actions on the visitor's behalf, for example, in a hidden iframe.<br />
● Solution<br />
Include a random token in the POST submission which is validated on the server-side. Only if this token is<br />
non-predictable for attackers can one prevent cross-site, request-forgery attacks. The easiest way to prevent<br />
cross-site, request-forgery attacks is by using the standard <strong>SAP</strong> <strong>HANA</strong> XS cookie. This cookie is randomly<br />
and securely generated and provides a good random token which is unpredictable by an attacker<br />
($.session.getSecurityToken()).<br />
Incorrect security configuration<br />
● Problem<br />
No or an inadequate authentication mechanism has been implemented.<br />
● Solution<br />
Applications should have proper authentication in place, for example, by using <strong>SAP</strong> <strong>HANA</strong> built-in<br />
authentication mechanisms and, in addition, the <strong>SAP</strong> <strong>HANA</strong> XS cookie and session handling features.<br />
Application developers must also consider and control which paths are exposed by HTTP to the outside world<br />
and which of these paths require authentication.<br />
Insecure cryptographic storage<br />
● Problem<br />
Sensitive information such as logon credentials is exposed.<br />
● Solution<br />
To prevent unauthorized access, for example, in the event of a system break-in, data such as user logon<br />
credentials must be stored in an encrypted state. Application developers can use the <strong>SAP</strong> <strong>HANA</strong> XS API,<br />
which provides a secured key value store.<br />
Missing restrictions on URL Access<br />
● Problem<br />
Unauthenticated users have access to URLs that expose confidential (unauthorized) data.<br />
● Solution<br />
216<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
Make sure you have addressed the issues described in "Broken Authentication and Session Management"<br />
and "Insecure Direct Object References". In addition, check if a user is allowed to access a specific URL before<br />
actually executing the code behind that requested URL. Consider putting an authentication check in place for<br />
each JavaScript file before continuing to send any data back to the client's Web browser.<br />
Insufficient transport layer protection<br />
● Problem<br />
Without transport-layer protection, the user's network traffic can be monitored, and attackers can steal<br />
sensitive information such as logon credentials or credit-card data.<br />
● Solution<br />
Turn on transport-layer protection in <strong>SAP</strong> <strong>HANA</strong> XS; the procedure is described in the <strong>SAP</strong> <strong>HANA</strong> security<br />
guide.<br />
Invalidated redirects and forwards<br />
● Problem<br />
Web applications frequently redirect users to other pages or use internal forwards in a similar manner.<br />
Sometimes the target page is specified in an invalid (not permitted) parameter. This enables an attacker to<br />
choose a destination page leading to the possibility of phishing attacks or the spamming of search engines.<br />
● Solution<br />
To prevent invalidated redirects or forwards, application developers should validate the requested destination<br />
before forwarding, for example, by checking if the destination is present in a whitelist.<br />
XML processing issues<br />
● Problem<br />
There are several potential security issues related to processing XML as input or to generating XML as output.<br />
In addition, problems with related technologies (such as XSLT) can enable the inclusion of other (unwanted)<br />
files.<br />
● Solution<br />
Bear the following rules and suggestions in mind when processing or generating XML output:<br />
○ When processing XML coming form an untrusted source, disable DTD processing and entity expansion<br />
unless strictly required. This helps prevent Billion Laugh Attacks (Cross-Site Request Forgery), which can<br />
bring down the processing code and, depending on the configuration of the machine, an entire server.<br />
○ To prevent the inclusion (insertion) of unwanted and unauthorized files, restrict the ability to open files or<br />
URLs even in requests included in XML input that comes from a trusted source. In this way, you prevent<br />
the disclosure of internal file paths and internal machines.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 217
○ Ensure proper limits are in place on the maximum amount of memory that the XML processing engine<br />
can use, the amount of nested entities that the XML code can have, and the maximum length of entity<br />
names, attribute names, and so on. This practice helps prevent the triggering of potential issues.<br />
9.2.4 Writing Server-Side JavaScript Applications<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) supports server-side application programming in<br />
JavaScript. The server-side application you develop can use a collection of JavaScript APIs to expose authorized<br />
data to client requests, for example, to be consumed by a client GUI such as a Web browser including <strong>SAP</strong>UI5<br />
applications and mobile clients.<br />
Since JavaScript programs are stored in the <strong>SAP</strong> <strong>HANA</strong> repository, the steps in this task description assume that<br />
you have already created a workspace and a project (of type XS Project), and that you have shared the project<br />
with other members of the development team. To write a server-side JavaScript application, you must perform<br />
the following high-level steps.<br />
1. Create a root package for your application, for example, helloxsjs.<br />
2. Create an application descriptor for your application and place it in the root package you created in the<br />
previous step.<br />
The application descriptor is the core file that you use to describe an application's availability within <strong>SAP</strong><br />
<strong>HANA</strong> Extended Application Services. The application-descriptor file has no contents and no name; it only has<br />
the file extension .xsapp.<br />
Note: For backward compatibility, content is allowed in the .xsapp file but ignored.<br />
3. Create an application-access file and place it in the package to which you want to grant access.<br />
The application-access file does not have a name; it only has the file extension .xsaccess. The contents of<br />
the .xsaccess file must be formatted according to JavaScript Object Notation (JSON) rules and associated<br />
with the package the file belongs to. The rules defined in the .xsaccess file apply to the package it resides in<br />
as well as any subpackages lower in the package hierarchy.<br />
4. If you used the authorization keyword in the application-access file (.xsaccess) file for your application,<br />
create an application-privileges file for the application and define the application privileges.<br />
The application-privileges file does not have a name; it only has the file extension .xsprivileges. The<br />
contents of the .xsprivileges file must be formatted according to JavaScript Object Notation (JSON)<br />
rules. Multiple .xsprivileges files are allowed, but only at different levels in the package hierarchy; you<br />
cannot place two .xsprivileges files in the same application package. The privileges defined in<br />
a .xsprivileges file are bound to the package to which the file belongs and can only be applied to this<br />
package and its subpackages.<br />
Note: The .xsprivileges file lists the authorization levels available for granting to an application<br />
package; the .xsaccess file defines which authorization level is assigned to which application<br />
package.<br />
5. Create the server-side JavaScript files that contain the application logic.<br />
218<br />
You can use the available JavaScript APIs (for example, the database or request-processing API) to expose<br />
authorized data to client requests.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
Server-side JavaScript files have the file suffix .xsjs, for example, hello.xsjs and contain the code that is<br />
executed when <strong>SAP</strong> <strong>HANA</strong> XS handles a URL request.<br />
$.response.contentType = "text/plain";<br />
$.response.setBody( "Hello, World!");<br />
6. Check the layout workspace.<br />
Your application package structure should have a structure that looks like the following example:<br />
.<br />
\<br />
helloxsjs<br />
\.xsapp<br />
.xsaccess<br />
hello.xsjs<br />
7. Save and activate your changes and additions.<br />
8. View the results.<br />
The <strong>SAP</strong> <strong>HANA</strong> XS Web server enables you to view the results immediately after activation in the repository,<br />
for example: http://dbhost:80/helloxsjs/hello.xsjs<br />
9.3 Writing JavaScript Libraries<br />
9.3.1 Server-Side JavaScript Libraries<br />
The elements defined in normal server-side JavaScript programs cannot be accessed from other JavaScript<br />
programs. To enable the reuse of program elements, <strong>SAP</strong> <strong>HANA</strong> Extended Application Services support serverside<br />
JavaScript libraries.<br />
Server-side JavaScript libraries are a special type of JavaScript program that can be imported and called in other<br />
JavaScript programs. You can use JavaScript libraries to perform simple, repetitive tasks, for example, to handle<br />
forms and form date, to manipulate date and time strings, to parse URLs, and so on.<br />
Note: JavaScript libraries are internally developed extensions for <strong>SAP</strong> <strong>HANA</strong>.<br />
The following example shows how to import a JavaScript mathematics library using the import function:<br />
// import math lib<br />
$.import("sap.myapp.lib","math");<br />
// use math lib<br />
var max_res = $.sap.myapp.lib.math.max(3, 7);<br />
The import function requires the following parameters:<br />
● Package name<br />
Full name of the package containing the library object you want to import, for example, sap.myapp.lib<br />
● Library name<br />
Name of the library object you want to import, for example, math<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 219
9.3.2 Writing Server-Side JavaScript Libraries<br />
Server-side JavaScript libraries are a special type of JavaScript program that can be imported and called in other<br />
JavaScript programs. You can use JavaScript libraries to perform simple, repetitive tasks, for example, to handle<br />
forms and form date, to manipulate date and time strings, to parse URLs, and so on.<br />
JavaScript libraries are internally developed extensions for <strong>SAP</strong> <strong>HANA</strong>. However, you can write your own libraries,<br />
too. JavaScript libraries exist in the context of a package, which is referenced when you import the library. To<br />
write a JavaScript library to use in your server-side JavaScript application, perform the following steps:<br />
1. Create the file that contains the JavaScript library you want to add to the package and make available for<br />
import.<br />
In <strong>SAP</strong> <strong>HANA</strong> XS, server-side JavaScript libraries have the file extension .xsjslib, for example<br />
greetLib.xsjslib.<br />
The following example creates a simple library that displays the word “Hello” along with a supplied name and<br />
adds an exclamation point (!) as a suffix.<br />
var greetingPrefix = "Hello, ";<br />
var greetingSuffix = "!";<br />
function greet (name) {<br />
return greetingPrefix + name + greetingSuffix;<br />
}<br />
2. Save the new JavaScript library.<br />
It is important to remember where the JavaScript library is located; you have to reference the package path<br />
when you import the library.<br />
3. Activate your new library in the repository so that it is available for import by other JavaScript applications.<br />
9.3.3 Importing Server-Side JavaScript Libraries<br />
Server-side JavaScript libraries are a special type of JavaScript program that can be imported and called in other<br />
JavaScript programs. You can use JavaScript libraries to perform simple, repetitive tasks, for example: handle<br />
forms and form date, manipulate date and time strings, parse URLs, and so on.<br />
JavaScript libraries are internally developed extensions for <strong>SAP</strong> <strong>HANA</strong>. The libraries exist in the context of a<br />
package, which is referenced when you import the library. The following example of a JavaScript library displays<br />
the word "Hello" along with a name and an exclamation mark as a suffix.<br />
var greetingPrefix = "Hello, ";<br />
var greetingSuffix = "!";<br />
function greet (name) {<br />
return greetingPrefix + name + greetingSuffix;<br />
}<br />
Note: This procedure uses the illustrated example JavaScript library to explain what happens when you<br />
import a JavaScript library, for example, which objects are created, when, and where. If you have your own<br />
library to import, substitute the library names and paths shown in the steps below as required.<br />
To import a JavaScript library for use in your server-side JavaScript application, perform the following tasks<br />
1. Import the JavaScript library into a JavaScript application.<br />
220<br />
Open the server-side JavaScript file into which you want to import the JavaScript library.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
Use the $.import function, as follows:<br />
$.import("","greetLib");<br />
var greeting = $.path.to.your.library.filename.greet("World");<br />
$.response.setBody(greeting);<br />
2. Save and activate the changes to the JavaScript file.<br />
Although the operation is simple, bear in mind the following points:<br />
○ Additional objects in the package hierarchy<br />
The import operation generates a hierarchy of objects below $ that resemble the library's location in the<br />
repository, for example, for the library path/to/your/library/greetLib.xsjslib, you would see<br />
the following additional object:<br />
$.path.to.your.library.greetLib<br />
○ Additional properties for the newly generated library object:<br />
$.path.to.your.library.greetLib.greet()<br />
$.path.to.your.library.greetLib.greetingSuffix<br />
$.path.to.your.library.greetLib.greetingPrefix<br />
○ Pre-import checks:<br />
○ It is not possible to import the referenced library if the import operation would override any<br />
predefined runtime objects.<br />
○ Do not import the referenced library if it is already present in the package.<br />
○ Library context<br />
Imported libraries exist in the context defined by their repository location.<br />
9.4 Server-Side JavaScript APIs<br />
<strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS) provides a set of server-side JavaScript application<br />
programming interfaces (API) that enable you to configure your applications to interact with <strong>SAP</strong> <strong>HANA</strong>.<br />
The <strong>SAP</strong> <strong>HANA</strong> XS API Reference lists all the functions that are available for use when programing interaction<br />
between your application and <strong>SAP</strong> <strong>HANA</strong>. For example, you can use the database API to invoke SQL statements<br />
from inside your application, or access details of the current HTTP request for <strong>SAP</strong> <strong>HANA</strong> data with the requestprocessing<br />
API.<strong>SAP</strong> <strong>HANA</strong> XS includes the following set of server-side JavaScript APIs:<br />
● Request-Processing API<br />
Enables access to the context of the current HTTP request, for example, for read requests and write<br />
responses. You can use the functions provided by this API to manipulate the content of the request and the<br />
response.<br />
● Database API<br />
Enables access to the <strong>SAP</strong> <strong>HANA</strong> by means of SQL statements. For example, you can open a connection to<br />
commit or rollback changes in <strong>SAP</strong> <strong>HANA</strong>, to prepare stored procedures (or SQL statements) for execution or<br />
to return details of a result set or a result set's metadata.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 221
Request-Processing API Example<br />
The following example shows how to use the request-processing API to display the message “Hello World” in a<br />
browser.<br />
$.response.contentType = "text/plain";<br />
$.response.setBody( "Hello, World !");<br />
Database API Example<br />
The following example shows how to use the database API to prepare and execute an SQL statement. The<br />
response to the SQL query is then prepared and displayed in a Web browser.<br />
var conn = $.db.getConnection();<br />
var pstmt = conn.prepareStatement( "select * from DUMMY" );<br />
var rs = pstmt.executeQuery();<br />
$.response.contentType = "text/plain";<br />
if (!rs.next()) {<br />
$.response.setBody( "Failed to retreive data" );<br />
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;<br />
} else {<br />
$.response.setBody("Response: " + rs.getString(1));<br />
}<br />
rs.close();<br />
pstmt.close();<br />
conn.close();<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> XS JavaScript Reference<br />
9.5 The SQL Connection Configuration File<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), you use the SQL-connection configuration file to<br />
enable the execution of SQL statements from inside your server-side JavaScript application with credentials that<br />
are different to the credentials of the requesting user.<br />
In cases where it is necessary to execute SQL statements from inside your JavaScript application with credentials<br />
that are different to the credentials of the requesting user, <strong>SAP</strong> <strong>HANA</strong> XS enables you to define the configuration<br />
for individual SQL connections. Each connection configuration has a unique name, for example, Registration or<br />
AdminConn, which is generated from the name of the corresponding connection-configuration file<br />
(Registration.xssqlcc or AdminConn.xssqlcc) on activation in the repository. The administrator can<br />
assign specific, individual database users to this configuration, and you can use the configuration name to<br />
reference the unique SQL connection configuration from inside your JavaScript application code.<br />
If you want to create an SQL connection configuration, you must create the configuration as a flat file and save the<br />
file with the suffix .xssqlcc, for example, MYSQLconnection.xssqlcc. The new configuration file must be<br />
located in the same package as the application that references it. You can activate repository files at any point in<br />
time.<br />
222<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
Note: A SQL connection configuration can only be accessed from a <strong>SAP</strong> <strong>HANA</strong> XS JavaScript application<br />
(.xsjs) file that is in the same package as the SQL connection configuration itself. Neither subpackages<br />
nor sibling packages are allowed to access an SQL connection configuration.<br />
The following example shows the composition and structure of a configuration file AdminConn.xssqlcc for an<br />
<strong>SAP</strong> <strong>HANA</strong> XS SQL connection called AdminConn. On activation of the SQL connection configuration file<br />
AdminConn.xssqlcc (for example, in the package sap.hana.sqlcon), an SQL connection configuration with<br />
the name sap.hana.sqlcon::AdminConn is created, which can be referenced in your JavaScript application.<br />
sap.hana.sqlcon:AdminConn.xssqlcc<br />
{<br />
}<br />
"description" : "Admin SQL connection"<br />
To create a preconfigured SQL connection using the configuration object AdminConn, for example, from inside<br />
your JavaScript application code, you reference the object using the object name and full package path, as<br />
illustrated in the following code example.<br />
Calling the <strong>SAP</strong> <strong>HANA</strong> XS SQL-Connection Configuration File<br />
function test() {<br />
var body;<br />
var conn;<br />
$.response.status = $.net.http.OK;<br />
try {<br />
conn = $.db.getConnection("sap.hana.sqlcon::AdminConn");<br />
var pStmt = conn.prepareStatement("select CURRENT_USER from<br />
dummy");<br />
var rs = pStmt.executeQuery();<br />
if (rs.next()) {<br />
body = rs.getNString(1);<br />
}<br />
rs.close();<br />
pStmt.close();<br />
} catch (e) {<br />
body = "Error: exception caught";<br />
$.response.status = $.net.http.BAD_REQUEST;<br />
}<br />
if (conn) {<br />
conn.close();<br />
}<br />
$.response.setBody( body );<br />
}<br />
test();<br />
To use the SQL connection from your application during runtime, you must bind the SQL connection configuration<br />
to a database user. To maintain this user mapping, <strong>SAP</strong> <strong>HANA</strong> XS provides a dedicated application (the SQL<br />
Connection Configuration Application), which is pre-installed and accessible under the URL http://<br />
:/sap/hana/xs/sqlcc/. You can grant one of the following roles for users who want to use the<br />
SQL Connection Configuration Application to view or maintain the available SQL connection configurations:<br />
● sap.hana.xs.sqlcc::Viewer<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 223
Required to display the available SQL Connections and the current user mapping<br />
● sap.hana.xs.sqlcc::Administrator<br />
Required to change the user mapping<br />
9.6 Tracing JavaScript<br />
9.6.1 Server-Side JavaScript Tracing<br />
The <strong>SAP</strong> <strong>HANA</strong> XS server-side JavaScript API provides tracing functions that enable your application to write<br />
predefined messages in the form of application-specific trace output in the xsengine trace files (xsengine*.trc)<br />
according to the trace level you specify, for example, “info”(information) or “error”.<br />
If you use the server-side JavaScript API to enable your application to write trace output, you can choose from the<br />
following trace levels:<br />
● debug<br />
● info<br />
● warning<br />
● error<br />
● fatal<br />
For example, to enable debug-level tracing for your JavaScript application:<br />
$.trace.debug("request path: " + $.request.path);<br />
Note: You can view the xsengine*.trace files in the Diagnosis Files tab page in the Administration<br />
perspective of the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
9.6.2 Tracing Server-Side JavaScript Applications<br />
The server-side JavaScript API for <strong>SAP</strong> <strong>HANA</strong> XS enables you to activate the writing of trace messages into an<br />
application-specific trace file; the following trace levels are available: debug, error, fatal, info, and warning.<br />
By default, applications write messages of severity level error to the xsengine*.trc trace files; you can increase<br />
the trace level manually, for example, to fatal. In <strong>SAP</strong> <strong>HANA</strong> XS, the following steps are required to enable trace<br />
output for your server-side JavaScript application:<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. In the Navigator view, double-click the <strong>SAP</strong> <strong>HANA</strong> instance to open the Administration view for the repository<br />
where your server-side JavaScript source files are located.<br />
3. Choose the Trace Configuration view.<br />
4. In the Global Database Trace screen area, choose Edit Configuration.<br />
The Edit Configuration icon is only visible if you have the required privileges on the selected <strong>SAP</strong> <strong>HANA</strong><br />
system.<br />
5. Select the Show All Components checkbox.<br />
6. Enter the partial or full name of your application into the search box.<br />
7. Expand the GLOBAL node, if necessary, to view registered traces for the application name returned by the<br />
search operation.<br />
224<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
8. Find the trace matching your application name and select the trace level you want to use to generate output.<br />
The application name is the location (package) of the .xsapp file associated with the application you are<br />
tracing. The trace topic is named xsa: .<br />
9. Choose Finish to activate the trace level changes.<br />
9.6.3 Viewing Server-Side JavaScript Application Trace Files<br />
The server-side JavaScript API for <strong>SAP</strong> <strong>HANA</strong> XS enables you to instruct your JavaScript applications to write<br />
application-specific trace messages in the xsengine*.trc trace files, which you can view in the Diagnosis Files<br />
tab page of the Administration perspective in the <strong>SAP</strong> <strong>HANA</strong> studio. The following trace levels are available:<br />
debug, error, fatal, info, and warning.<br />
To view trace output for your server-side JavaScript application, perform the following steps:<br />
1. Open the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
2. In the Navigator view, double-click the <strong>SAP</strong> <strong>HANA</strong> instance to open the Administration view for the repository<br />
where your server-side JavaScript source files are located.<br />
3. Choose the Diagnosis Files tab page.<br />
4. In the Filter box, enter a string to filter the list of search files displayed, for example, xsengine*.trc.<br />
The timestamp displayed in the Modified column does not always reflect the precise time at which the trace<br />
file was written or most recently modified.<br />
5. Locate the trace file for your <strong>SAP</strong> <strong>HANA</strong> XS application and doubleclick the entry to display the contents of<br />
the selected trace-file in a separate tab page.<br />
9.7 Debugging JavaScript<br />
<strong>SAP</strong> <strong>HANA</strong> studio enables you to debug XS JavaScript files, including setting breakpoints and inspecting<br />
variables.<br />
Caution: A port must be opened to enable debugging. For security reasons, the debug port is turned off by<br />
default.<br />
1. In a browser, run the XS JavaScript source file that you want to debug.<br />
2. Create a debug configuration for debug sessions for a specific <strong>SAP</strong> <strong>HANA</strong> installation.<br />
a) Open the Debug perspective.<br />
b) Choose and select Debug Configurations.<br />
c) Create a new XS JavaScript configuration by double-click XS JavaScript.<br />
d) Enter a name for the configuration.<br />
e) Enter the host and debug port for your <strong>SAP</strong> <strong>HANA</strong> system.<br />
f) Select Apply.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 225
g) Select Close.<br />
3. Set breakpoints in the JavaScript code by double-clicking on the left vertical ruler.<br />
4. Run your debug configuration for your server by choosing and selecting your debug configuration.<br />
5. In the Select Session window, select the <strong>SAP</strong> <strong>HANA</strong> XS session ID you are debugging, and then click Select.<br />
226<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
The session ID is the value of the xsSessionId cookie in your browser session.<br />
6. Refresh the browser. The XS JavaScript is now running in debug mode. Your client is now attached to the<br />
session, and execution is suspended at the first breakpoint.<br />
You can now perform standard Eclipse debug tasks, such as resuming execution, stepping through execution, and<br />
adding breakpoints. The following debug views are available:<br />
● Debug<br />
● Breakpoints<br />
● Variables<br />
● Expressions, which you can use to inspect global variables, such as $.request and other <strong>SAP</strong> <strong>HANA</strong> XS<br />
JavaScript API objects<br />
Related Links<br />
Debug Perspective [page 30]<br />
The Debug perspective in the <strong>SAP</strong> <strong>HANA</strong> studio is the standard Eclipse Debug perspective, enabling you to<br />
start debug sessions, create breakpoints and watch variables.<br />
Opening a Port for JavaScript Debugging [page 227]<br />
9.7.1 Opening a Port for JavaScript Debugging<br />
To enable debugging of JavaScript code, you must open a debug port on <strong>SAP</strong> <strong>HANA</strong>.<br />
The debug port is unsecured, as anyone can attach a debug client without needing credentials. A connected client<br />
can attach to and debug any HTTP session, and can possibly run their own code.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 227
Therefore, it is recommended that you enable this feature only in non-production or development environments<br />
that are accessible by a limited number of developers and that do not contain sensitive and confidential data. In<br />
production systems that contain sensitive or confidential data, it is recommended that you keep debugging<br />
disabled or enable it only temporarily.<br />
To increase security, customers should consider applying additional network-level security measures, for<br />
example, limiting network access to the debug port.<br />
1. In <strong>SAP</strong> <strong>HANA</strong> studio, open the Navigator view.<br />
2. Right-click on your system, and selct Administration.<br />
3. In the Configuration tab, add a section called xsengine.ini debugger (if it does not exist) and add the<br />
following parameters:<br />
228<br />
○ enabled = true<br />
○ listenport = <br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Writing Server-Side JavaScript Applications
10 Building UIs with <strong>SAP</strong>UI5<br />
This section provides introductory information about UI development toolkit for HTML5.<br />
UI development toolkit for HTML5 (<strong>SAP</strong>UI5) is a user interface technology that is used to build and adapt client<br />
applications based on <strong>SAP</strong> <strong>HANA</strong>. You can install <strong>SAP</strong>UI5 in the <strong>SAP</strong> <strong>HANA</strong> studio to build user interfaces<br />
delivered by <strong>SAP</strong> <strong>HANA</strong>'s Web server.<br />
<strong>SAP</strong>UI5 runtime is a client-side HTML5 rendering library with a rich set of standard and extension controls and a<br />
lightweight programming model. To support you in developing applications, <strong>SAP</strong>UI5 application development<br />
tools comes with a set of eclipse-based wizards and editors. <strong>SAP</strong>UI5 application development tools provides<br />
wizards to create application projects and views according to the model-view-controller concept and other<br />
features like JavaScript code completion, templates and snippets, and in-place application preview.<br />
<strong>SAP</strong>UI5 provides many features to enable you to easily create and extend state-of-the-art user interfaces. <strong>SAP</strong>UI5<br />
supports the following features:<br />
● RIA-like client-side features based on JavaScript.<br />
● CSS3, which allows you to adapt themes to your company's branding in an effective manner<br />
● Extensibility concept regarding custom controls, meaning that you can extend existing <strong>SAP</strong>UI5 controls as<br />
well as develop your own controls<br />
● Open source jQuery library used as foundation<br />
● Full support of the <strong>SAP</strong> product standard<br />
● Compliance to Open Ajax; can be used together with standard JavaScript libraries<br />
● Produced in a release independent code line to enable short shipment cycles<br />
<strong>SAP</strong>UI5 SDK<br />
The <strong>SAP</strong>UI5 SDK (Demo Kit) provides the following sections:<br />
● <strong>Developer</strong> <strong>Guide</strong> with additional information about <strong>SAP</strong>UI5, the used programming languages, open source<br />
technologies, development tools, and APIs<br />
● Controls containing running demo examples with descriptions and source codes<br />
● API reference with JavaScript documentation of Framework and Control API<br />
● Test Suite, which shows all controls running with different property settings where you can interactively adapt<br />
the controls you use for test purposes<br />
The Demo Kit is installed as a delivery unit. To directly access the Demo Kit, use the following link and replace the<br />
placeholders accordingly: ://:/sap/ui5/1/sdk/index.html.<br />
The following references to the sections of the <strong>Developer</strong> <strong>Guide</strong> in the Demo Kit base on this URL.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Building UIs with <strong>SAP</strong>UI5<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 229
10.1 Installing <strong>SAP</strong>UI5 Application Development Tools<br />
This section provides a short description how to install <strong>SAP</strong>UI5 tools for <strong>SAP</strong> <strong>HANA</strong>.<br />
Before you start the installation of <strong>SAP</strong>UI5 application development tools, make sure that you comply with the<br />
following requirements:<br />
● <strong>SAP</strong> <strong>HANA</strong> studio is installed.<br />
● <strong>SAP</strong>UI5 application development tools are downloaded from the <strong>SAP</strong> Software Download Center on <strong>SAP</strong><br />
Service Marketplace (http://service.sap.com/swdc) and search for <strong>SAP</strong>UI5 TOOLS IDE PLUGIN 1.00.<br />
For more information about the installation of <strong>SAP</strong>UI5 application development tools, see the <strong>SAP</strong>UI 5 Installation<br />
<strong>Guide</strong> for <strong>SAP</strong> <strong>HANA</strong> on <strong>SAP</strong> Service Marketplace or <strong>SAP</strong> Note 1747308.<br />
10.2 Creating an <strong>SAP</strong>UI5 Application<br />
This section provides an example how to create an <strong>SAP</strong>UI5 application.<br />
Prerequisites: You have installed the <strong>SAP</strong>UI5 application development tools in your <strong>SAP</strong> <strong>HANA</strong> studio.<br />
Using the tools <strong>SAP</strong>UI5 provides, you create application projects and views according to the model-view-<br />
controller concept with a clear separation between the user interface and the controller logic.<br />
The following steps describe the generic procedure to create an <strong>SAP</strong>UI5 application for <strong>SAP</strong> <strong>HANA</strong> XS:<br />
1. Create an <strong>SAP</strong>UI5 application project using <strong>SAP</strong>UI5 application development tools in Eclipse.<br />
2. Develop the client-side JavaScript script code.<br />
3. If the package that contains your <strong>SAP</strong>UI5 application project has not been exposed via HTTP already, you<br />
need to create .xsapp and .xsaccess files, see Creating the Application Descriptors. This is not necessary, if<br />
the project was created as a sub-package of an <strong>SAP</strong> <strong>HANA</strong> XS application. To make this project a valid <strong>SAP</strong><br />
<strong>HANA</strong> application, add the .xsapp and .xsaccess files.<br />
4. Optional step (not part of the example below): Develop a server-side logic for the project by means of server-<br />
side JavaScript or OData service.<br />
5. Activate the project on <strong>SAP</strong> <strong>HANA</strong>'s Web server.<br />
6. Execute the application on <strong>SAP</strong> <strong>HANA</strong>'S Web server.<br />
For <strong>SAP</strong>UI5 applications, the following view types are supported:<br />
● JavaScript: JSview (file extension: js)<br />
● XML: XMLview (file extension: xml)<br />
● JSON: JSONview (file extension: json)<br />
The following procedure gives an example for the creation of an <strong>SAP</strong>UI5 application:<br />
1. To open the wizard for creating an <strong>SAP</strong>UI5 application, choose File New Other <strong>SAP</strong>UI5 Application<br />
230<br />
Development Application Project .<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Building UIs with <strong>SAP</strong>UI5
2. Specify the name, for example MyApplication, and location for your project. Select Desktop and Create an<br />
Initial View.<br />
You can also add a view later on by creating a separate <strong>SAP</strong>UI5 application view. If a new view has been<br />
created for an existing <strong>SAP</strong>UI5 application project, the view needs to be manually called either from the<br />
index.html page, or from another view via view nesting. For more information, see the Demo Kit -<br />
<strong>Developer</strong> <strong>Guide</strong> under Model View Controller Concept.<br />
3. Enter a name for the initial view in the Name field, for example, helloworld. Do not add a file extension.<br />
This is done automatically based on the respective view type.<br />
4. Choose JavaScript and finish the wizard.<br />
The following application parts are created:<br />
○ View file; in this example, a JSview file<br />
○ Controller file<br />
○ index.html file containing the references for the sap.ui.core and sap.ui.commons libraries, the<br />
theme (sap_goldreflection), and information about the script type and the script ID. In a second script<br />
block, the index file refers to the project name, view type, and name. A content default for placing the<br />
controls on the UI later on and the ARIA application role.<br />
5. Change the bootstrap tag (located in the index.html file) to enable the application to access the <strong>SAP</strong>UI5<br />
libraries on the xsengine as follows: src="resources/sap-ui-core.js" to src="/sap/ui5/1/<br />
resources/sap-ui-core.js".<br />
6. Create a new folder i18n in the WebContent folder. Add a new file messagebundle.hdbtextbundle<br />
to the i18n folder with the following content:<br />
# TRANSLATE<br />
# XBUT,30<br />
MY_BUTTON_TEXT=Hello {0} button<br />
Note: A specific suffix .hdbtextbundle is needed for the resource bundles on <strong>SAP</strong> <strong>HANA</strong> (so<br />
called .properties file on other platforms).<br />
7. To add a control to your view (in this example to the helloworld.view.js), insert the following coding:<br />
createContent : function(oController) {<br />
// require the jQuery.sap.resources module<br />
jQuery.sap.require("jquery.sap.resources");<br />
value<br />
}<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Building UIs with <strong>SAP</strong>UI5<br />
// load the resource bundle<br />
var oBundle = jQuery.sap.resources({<br />
// specify url of the .hdbtextbundle<br />
url : "i18n/messagebundle.hdbtextbundle"<br />
});<br />
var aControls = [];<br />
var oButton = new sap.ui.commons.Button({<br />
id : this.createId("MyButton"),<br />
// access the text using the welcome key and pass the<br />
// for the placeholder ( {0} ) via an array<br />
text : oBundle.getText("MY_BUTTON_TEXT", [ "World" ])<br />
});<br />
aControls.push(oButton.attachPress(oController.doIt));<br />
return aControls;<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 231
The coding is put into the createContent method, which creates the content of the view. The View<br />
wizard creates the body of the method.<br />
Note: In your <strong>SAP</strong>UI5 coding, refer to the resource bundle with the URL containing the file extension,<br />
for example:<br />
var oBundle = jQuery.sap.resources({<br />
url : "i18n/messagebundle.hdbtextbundle",<br />
locale: sLocale})<br />
var oResourceModel = new sap.ui.model.resource.ResourceModel({<br />
bundleURL : "i18n/messagebundle.hdbtextbundle "})<br />
8. To implement the doIt method for the button's press event, insert the following coding into the controller (in<br />
this example: helloworld.controller.js):<br />
doIt : function(oEvent) { alert(oEvent.getSource().getId() +<br />
"does it!"); }<br />
9. Create a .xsapp and a .xsaccess file.<br />
10. Share, commit, and activate your project to transfer the <strong>SAP</strong>UI5 application to the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
11. To start the UI application on <strong>SAP</strong> <strong>HANA</strong>'s Web server, use the following URL: ://:/MyApplication/WebContent/<br />
index.html. Replace the placeholders accordingly; MyApplication refers to the name of your project<br />
according to Step 2.<br />
10.2.1 Local Testing of a <strong>SAP</strong>UI5 Application<br />
This section provides a description how local testing can be performed as an optional step.<br />
If you want to test the <strong>SAP</strong>UI5 application before you activate your project, you can test it within Eclipse on your<br />
local PC. This local testing is optional. If you perform a local test, note the following:<br />
● The src attribute in the bootstrap tag of the index.html file needs to have a different URL than the src<br />
attribute for execution on <strong>SAP</strong> <strong>HANA</strong>'s Web server. This can be achieved by manually changing the URL<br />
before submitting to <strong>SAP</strong> <strong>HANA</strong>'s Web server, or by using a code snippet, that detects if the application runs<br />
locally or not, and sets the URL accordingly.<br />
● If you call a data service in form of a server-side JavaScript or an OData service that resides in the <strong>SAP</strong> <strong>HANA</strong><br />
box, it is necessary to use a URL that points to <strong>SAP</strong> <strong>HANA</strong>'s Web server. It is usually also necessary to use the<br />
so-called proxy servlet to avoid cross-domain issues. In case of the bootstrap URL, for example, the URL for<br />
local execution differs from the URL for execution on <strong>SAP</strong> <strong>HANA</strong>'s Web server. For more information, see the<br />
procedure below and the referenced section in the Demo Kit.<br />
For more information, see the Demo Kit - <strong>Developer</strong> <strong>Guide</strong> under Testing a <strong>SAP</strong>UI5 Application.<br />
To perform a local test, proceed as follows:<br />
1. Change the URL set as "src" in the bootstrap tag of the index.html file (see explanation above). To avoid<br />
232<br />
a manual change before submitting the application, use the following code snippet that detects the context<br />
automatically, in which the application runs, and sets the URL accordingly.<br />
<br />
<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Building UIs with <strong>SAP</strong>UI5
<br />
// use alternative bootstrap for testing locally in<br />
// Eclipse during development time<br />
// this is only a helper mechanism during development time<br />
if (!window.sap) {<br />
var oriTag = document.getElementById("sap-ui-bootstrap");<br />
oriTag.id = "wrong";<br />
oriTag.src = "wrong.js";<br />
var script = " " +<br />
"";<br />
document.write(script);<br />
}<br />
<br />
2. If you use requests to backend services, you need to use a suitable URL that points to the backend server and,<br />
to avoid cross-domain issues, you need to use the so-called proxy servlet. Similar to the bootstrap tag, you<br />
can change the respective code manually before submitting, or you can use a code snippet that determines<br />
the URL automatically depending on the context, in which the application runs.<br />
Note: As the server-side logic of an <strong>SAP</strong>UI5 application cannot be executed locally on the developer's<br />
PC, it can only run on the server. Hence, this needs to be committed and activated before it can be<br />
tested.<br />
For more information, see the Demo Kit - <strong>Developer</strong> <strong>Guide</strong> under Testing a <strong>SAP</strong>UI5 Application Enabling<br />
Backend Access for Local Testing .<br />
3. To test your application, choose one of the following options:<br />
○ Open the context menu for the index.html file located in your project's WebContent folder and<br />
choose Run As Web App Preview .<br />
○ To run your application on a server, for example Tomcat, open the context menu of your project, choose<br />
Run As Run on Server and select the respective server.<br />
10.2.2 <strong>SAP</strong>UI5 Runtime Version Comparison<br />
This section describes how to compare the <strong>SAP</strong>UI5 runtime versions installed locally and on <strong>SAP</strong> <strong>HANA</strong>' Web<br />
server.<br />
It is possible that the <strong>SAP</strong>UI5 runtime version installed locally in your Eclipse differs from the <strong>SAP</strong>UI5 runtime<br />
version on <strong>SAP</strong> <strong>HANA</strong>'s Web server.<br />
To verify, which version is installed locally, you can check the <strong>SAP</strong> <strong>HANA</strong> studio Eclipse version via Help About<br />
<strong>SAP</strong> <strong>HANA</strong> Studio Installation Details Features under "<strong>SAP</strong>UI5 Feature"<br />
(com.sap.ui5.uilib.feature).<br />
To find out the <strong>SAP</strong>UI5 runtime version on <strong>SAP</strong> <strong>HANA</strong>'s Web server, open the <strong>SAP</strong> <strong>HANA</strong> modeler perspective in<br />
the <strong>SAP</strong> <strong>HANA</strong> studio Eclipse via Window Open Perspective Modeler . Choose Setup Delivery Units ...<br />
. The version, support package, and patch version of the <strong>SAP</strong>UI5 runtime libs are displayed there. You can also<br />
open the <strong>SAP</strong>UI5 runtime index page under ://:/sap/ui5/1/<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Building UIs with <strong>SAP</strong>UI5<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 233
index.html and press CTRL-ALT-SHIFT-P. The <strong>SAP</strong>UI5 runtime version is displayed in the field.<br />
If the local version is, for example, newer than the version on <strong>SAP</strong> <strong>HANA</strong>'s Web server and you use code<br />
completion or test the application locally in Eclipse, the results may differ or you may use features that are not<br />
available on the server. We recommend the following:<br />
● To detect new features, check the @since tags provided in the JSDoc.<br />
● Before deployment, test the application locally in Eclipse with the runtime resources from the server by<br />
configuring the resource servlet to fetch the runtime resources from the server. For more information, see the<br />
Demo Kit - <strong>Developer</strong> <strong>Guide</strong> under Testing an <strong>SAP</strong>UI5 Application UI5 Library Location Used for Testing .<br />
● After deployment, always test the application on the server.<br />
10.3 Supporting Translation<br />
This section provides a description of what needs to be done to support the translation of resource bundles.<br />
To enable the translation of the user interface, define a specific suffix for the resource bundles and use a specific<br />
first line in the resource bundle file. This is described in step 6 in the Creating an <strong>SAP</strong>UI5 Application topic.<br />
For more information, see the Demo Kit - <strong>Developer</strong> <strong>Guide</strong> under Localization.<br />
Related Links<br />
Creating an <strong>SAP</strong>UI5 Application [page 230]<br />
This section provides an example how to create an <strong>SAP</strong>UI5 application.<br />
234<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Building UIs with <strong>SAP</strong>UI5
11 Enabling Search<br />
With a <strong>SAP</strong> <strong>HANA</strong> database, your users will want to search tables and views much like they would when searching<br />
for information on the Internet. In <strong>SAP</strong> <strong>HANA</strong>, you can either directly query data using SQL queries or you can<br />
build search apps using a UI toolkit.<br />
Before enabling search, you must meet the following prerequisites:<br />
● Your <strong>SAP</strong> <strong>HANA</strong> database contains column-oriented tables.<br />
● A valid data type is assigned to each column. The data types of the columns determine how you can query<br />
your data.<br />
In <strong>SAP</strong> <strong>HANA</strong>, you can search on single or multiple columns of almost any visible data type. In addition to standard<br />
string search, <strong>SAP</strong> <strong>HANA</strong> also supports full text search.<br />
During a full text search, the <strong>SAP</strong> <strong>HANA</strong> search engine examines structured text, such as author and date<br />
attributes, as well as unstructured text, such as body text. Unlike a string search, for a text search, the sequence<br />
of words and characters is not critical for finding matches. A full text index enables this functionality by analyzing<br />
and preprocessing the available text semantically. This includes normalization, tokenization, word stemming, and<br />
parts of speech tagging.<br />
To enable search, proceed as follows:<br />
1. Create any required full text indexes for the columns in the table.<br />
○ For columns defined with the data type TEXT or SHORTTEXT(n), full text indexes are automatically<br />
generated. For columns of any other data type, you must manually create any required full text indexes.<br />
○ When you create a full text index, you can also define synchronization and trigger text analysis.<br />
2. Build SQL search queries.<br />
○ Search queries use the SQL SELECT statement.<br />
○ For searches on large object types or text, the queries must include the CONTAINS predicate.<br />
3. Optionally, build search apps using the UI toolkit for <strong>SAP</strong> <strong>HANA</strong> Info Access .<br />
○ The UI toolkit provides UI building blocks for developing browser-based search apps for end users.<br />
○ The UI toolkit is based on HTML5 and JavaScript libraries.<br />
○ The UI toolkit connects to the database using the <strong>SAP</strong> <strong>HANA</strong> Info Access service that wraps search and<br />
analytic SQL queries and exposes them through an HTTP interface.<br />
11.1 Creating Full Text Indexes<br />
When you create a TEXT or SHORTTEXT column in a table, <strong>SAP</strong> <strong>HANA</strong> automatically creates a corresponding full<br />
text index. However, for columns of other data types, you must manually create and define any necessary full text<br />
indexes.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 235
A full text index is an additional data structure that is created to enable text search features on a specific column<br />
in a table. Conceptually, full text indexes support searching on columns in the same way that indexes support<br />
searching through books.<br />
To create a full text index, proceed as follows:<br />
1. Determine the columns for which you require an index.<br />
2. Use the CREATE FULLTEXT INDEX statement to create an index with the specified index name.<br />
CREATE FULLTEXT INDEX ON '(' ')'<br />
[]<br />
3. Specify any of the following additional parameters for the full text index:<br />
LANGUAGE COLUMN <br />
LANGUAGE DETECTION '(' ')'<br />
MIME TYPE COLUMN <br />
FUZZY SEARCH INDEX <br />
PHRASE INDEX RATIO <br />
CONFIGURATION <br />
SEARCH ONLY <br />
FAST PREPROCESS <br />
FUZZY SEARCH INDEX <br />
TEXT ANALYSIS <br />
SYNC<br />
|ASYNC<br />
|ASYNC FLUSH [QUEUE] EVERY n MINUTES<br />
|ASYNC FLUSH [QUEUE] AFTER n DOCUMENTS<br />
|ASYNC FLUSH [QUEUE] EVERY n MINUTES OR AFTER m DOCUMENTS<br />
If you do not specify any parameters, the default values are used.<br />
The system creates a separate hidden full text index column for each source column that you have specified.<br />
You can now create queries to search those columns.<br />
You can check the parameters of an existing full text index by using the SYS.FULLTEXT_INDEXES monitoring<br />
view.<br />
Related Links<br />
You want to create a full text index i1 for table A, column C, with the following characteristics:<br />
● Synchronous processing<br />
● Fuzzy search index disabled<br />
● Languages for language detection: English, German, and South Korean<br />
To create the index, you use the following syntax:<br />
CREATE FULLTEXT INDEX i1 ON A(C) FUZZY SEARCH INDEX OFF<br />
SYNC<br />
LANGUAGE DETECTION<br />
('EN','DE','KR')<br />
Full Text Index Types [page 237]<br />
<strong>SAP</strong> <strong>HANA</strong> automatically creates full text indexes for columns of type TEXT and SHORTTEXT(n). For other<br />
column types, you must manually create any required full text indexes.<br />
236<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Synchronization [page 240]<br />
Full text indexes in a <strong>SAP</strong> <strong>HANA</strong> database must be created and updated in synchronization with the<br />
corresponding columns. This synchronization can be either synchronous or asynchronous.<br />
Full Text Index Parameters [page 247]<br />
The content and behavior of a full text index is configured by the use of both default and user-specified<br />
parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.<br />
11.1.1 Full Text Index Types<br />
<strong>SAP</strong> <strong>HANA</strong> automatically creates full text indexes for columns of type TEXT and SHORTTEXT(n). For other<br />
column types, you must manually create any required full text indexes.<br />
Characteristic TEXT SHORTTEXT (n) Manually Created<br />
SQL data type exposed to<br />
user<br />
Data returned by SELECT Original data (returns<br />
normalized data if the<br />
SEARCH_ONLY parameter<br />
is ON)<br />
NCLOB NVARCHAR(n) Original data type<br />
Original data Original data<br />
SQL insertion mode SYNC SYNC SYNC or ASYNC<br />
Drop index Yes (via drop column) Yes (via drop column) Yes<br />
Text search via CONTAINS Yes Yes Yes<br />
SQL string search Not possible Possible Depends on underlying<br />
data type<br />
Change parameters of full<br />
text index<br />
Partially Partially All (with rebuild)<br />
Rebuild index No No Yes<br />
Base type can be changed No No No (no dependency<br />
between base-column and<br />
index available)<br />
TEXT Indexes<br />
In a <strong>SAP</strong> <strong>HANA</strong> database, when you create a table that contains large text documents, you can define the columns<br />
with the TEXT data type. This data type allows you to query large text documents and present content excerpts in<br />
search hit lists. You can also reconstruct the document and display it in its original formatting.<br />
When you create a TEXT column and insert content, <strong>SAP</strong> <strong>HANA</strong> extracts and processes the text from the original<br />
document and then automatically generates a full text index for the column. To create this full text index, <strong>SAP</strong><br />
<strong>HANA</strong> replaces the original data in the column with the processed text. This text is then returned with the data<br />
type NCLOB. The original data is no longer available.<br />
If you insert new entries in the TEXT column, the full text index is automatically and synchronously updated.<br />
CREATE COLUMN TABLE <br />
(<br />
k int primary key,<br />
content TEXT<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
FAST PREPROCESS OFF<br />
PHRASE INDEX RATIO<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 237
0.77<br />
)<br />
Limitations<br />
The TEXT data type has the following search-relevant limitations:<br />
● SQL string searches are not supported.<br />
● The SQL functions CONCAT and JOIN are not supported.<br />
● TEXT columns cannot be converted to other data types.<br />
● Text analysis is not supported.<br />
For TEXT columns, <strong>SAP</strong> <strong>HANA</strong> does not support the following SQL expressions:<br />
● HAVING<br />
● WHERE with strings or non-alphanumeric characters<br />
● ORDER BY<br />
● GROUP BY<br />
● Aggregate expressions (COUNT, MIN, MAX, etc.)<br />
● JOIN ON<br />
Changes to TEXT Indexes<br />
TEXT full text indexes are automatically generated and you do not specify names for them; therefore, you cannot<br />
directly manipulate them. However, when you create, alter, or drop a table column, the same change is<br />
automatically applied to the full text index for that column.<br />
By using the ALTER TABLE statement to affect changes on the index, you can alter the following parameters:<br />
● PHRASE INDEX RATIO<br />
● FUZZY SEARCH INDEX<br />
SHORTTEXT(n) Indexes<br />
If the tables in your <strong>SAP</strong> <strong>HANA</strong> database contain columns with text strings that are relatively short in length, you<br />
can define those columns with the SHORTTEXT(n) data type. The SHORTTEXT(n) data type enables both SQL<br />
string search and full text search capabilities.<br />
<strong>SAP</strong> <strong>HANA</strong> preprocesses the text in the column and stores that preprocessed text as a full text index in a hidden<br />
column attached to the original column. When queried, the text in the full text index returns with the NVARCHAR<br />
data type. The original text is still available; however, search queries are performed, by default, on the text in the<br />
index.<br />
When you create a column table and define a column with the data type SHORTTEXT(n), as in the following<br />
example, a full text index is automatically generated. Whenever new entries are then inserted in the column, the<br />
full text index is automatically and synchronously updated.<br />
238<br />
CREATE COLUMN TABLE <br />
(<br />
k int primary key,<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
)<br />
content SHORTTEXT(100)<br />
Changes to SHORTTEXT(n) Indexes<br />
FAST PREPROCESS OFF<br />
SEARCH ONLY ON<br />
SHORTTEXT(n) full text indexes are automatically generated and you do not specify names for them; therefore,<br />
you cannot directly manipulate them. However, when you create, alter, or drop a table column, the same change<br />
is automatically applied to the index for that column.<br />
When using the ALTER TABLE statement to affect changes on the index, you can only alter the following<br />
parameters:<br />
● PHRASE INDEX RATIO<br />
● FUZZY SEARCH INDEX<br />
Note: You cannot change the length of the original text and you cannot convert SHORTTEXT(n) to another<br />
data type.<br />
Manually Created Indexes<br />
If the tables in your <strong>SAP</strong> <strong>HANA</strong> database contain extensive columns that are frequently queried but do not have<br />
automatically generated full text indexes, meaning they are not TEXT or SHORTTEXT(n) type columns, you can<br />
improve search performance by manually creating full text indexes.<br />
To manually create a full text index, the column must have one of the following SQL data types:<br />
● VARCHAR<br />
● NVARCHAR<br />
● ALPHANUM<br />
● CLOB<br />
● NCLOB<br />
● BLOB<br />
When you manually create an index, the system attaches a hidden column to the specified column. This hidden<br />
column contains textual data that <strong>SAP</strong> <strong>HANA</strong> Preprocessor has extracted from the text in the source column. The<br />
original text in the source column remains unchanged. Search queries are then performed on the hidden column;<br />
however, they always return the original text. Depending on the data type that is assigned to a source column,<br />
string search may be possible.<br />
You can manually create an index directly after creating a table or you can create the index later. Once you create<br />
an index for a column, the system automatically processes any text that is inserted into this column and adds the<br />
processed text to the index. Processing for manually created indexes can be performed synchronously or<br />
asynchronously.<br />
You can specify different parameters when you create a full text index. If parameter changes are required later,<br />
you can change the values for the existing index directly or re-create the index with the parameters that you want<br />
to change.<br />
Related Links<br />
Creating Full Text Indexes [page 235]<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 239
When you create a TEXT or SHORTTEXT column in a table, <strong>SAP</strong> <strong>HANA</strong> automatically creates a corresponding<br />
full text index. However, for columns of other data types, you must manually create and define any necessary<br />
full text indexes.<br />
Altering Full Text Index Parameters [page 246]<br />
You can alter a full text index after it is created. Altering an index includes changing the values of the<br />
parameters and altering the parameters by replacing the index.<br />
Synchronization [page 240]<br />
Full text indexes in a <strong>SAP</strong> <strong>HANA</strong> database must be created and updated in synchronization with the<br />
corresponding columns. This synchronization can be either synchronous or asynchronous.<br />
Full Text Index Parameters [page 247]<br />
The content and behavior of a full text index is configured by the use of both default and user-specified<br />
parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.<br />
11.1.2 Synchronization<br />
Full text indexes in a <strong>SAP</strong> <strong>HANA</strong> database must be created and updated in synchronization with the<br />
corresponding columns. This synchronization can be either synchronous or asynchronous.<br />
Synchronous<br />
In <strong>SAP</strong> <strong>HANA</strong>, indexes of the type TEXT and SHORTTEXT(n) are synchronous. Text preprocessing is<br />
automatically performed when a column is created or new text is inserted and the full text index is then<br />
automatically updated. The system cannot transport any data to the proper database tables until text<br />
preprocessing is complete.<br />
Asynchronous<br />
If you manually create a full text index, you can specify whether the index is synchronous or asynchronous. By<br />
default, manually created indexes are asynchronous. Text preprocessing is not initially performed when the table<br />
or column is created or whenever new text is inserted. In this case, inserting the results of the text preprocessing<br />
and writing the original data do not occur at the same time. Therefore, the full text information may not be<br />
immediately available for searching.<br />
To handle asynchronous processing of text, <strong>SAP</strong> <strong>HANA</strong> uses queues.<br />
Queues<br />
The queue is a mechanism used to enable a full text index to operate asynchronously. This means that when you<br />
insert new entries into the column, the text is not made available in the column until it is preprocessed.<br />
When you insert new entries, the queue sends the text to the preprocessor for analysis. It returns a serialized<br />
instance of a DAF (document analysis format) object, which is then processed further by the <strong>HANA</strong> column store.<br />
The result is stored in the full text index.<br />
The <strong>SAP</strong> <strong>HANA</strong> queue manager automatically creates a queue when you create an asynchronous full text index or<br />
when the index server is started and the queue manager finds the information that a specific queue is needed. The<br />
queues are always created on the server on which the table is stored.<br />
Every entry in the queue has one of the following processing states:<br />
● New<br />
240<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
● Preprocessing<br />
● Preprocessed<br />
● Indexing<br />
● Error<br />
If the original column entry is modified or deleted during text processing, the queue is notified and, if necessary,<br />
the entry is preprocessed again.<br />
Note: The content of the queue is not made persistent at any stage. If the <strong>HANA</strong> index server process fails,<br />
the queue data is lost and the queue manager automatically restarts the process for those entries that<br />
were not already processed. Any incomplete text preprocessing is restarted from the beginning.<br />
Flush Scheduling<br />
When you create an asynchronous full text index, you can specify when documents are removed from the queue<br />
after they are preprocessed and inserted into the full text index; this is called flushing. You can schedule flushing<br />
based on either time or the number of documents. To do this, when you create the full text index, define one of the<br />
following clauses with the ASYNC parameter:<br />
● FLUSH EVERY (n) MINUTES<br />
● FLUSH AFTER (n) DOCUMENTS<br />
● FLUSH EVERY (n) MINUTES OR AFTER (m) DOCUMENTS<br />
Note: You cannot specify negatives values for minutes or documents.<br />
To determine when the queue of an existing full text index is flushed, see the FLUSH_EVERY_MINUTES and<br />
FLUSH_AFTER_ROWS attributes in the view FULLTEXT_INDEXES.<br />
Related Links<br />
Manipulating Queue Processing [page 241]<br />
By default, queues are active initially and run automatically based on the parameters you specify when<br />
creating the full text index. However, if necessary, you can manually manipulate the processing of an existing<br />
queue.<br />
Manipulating Queue Processing<br />
By default, queues are active initially and run automatically based on the parameters you specify when creating<br />
the full text index. However, if necessary, you can manually manipulate the processing of an existing queue.<br />
To manipulate the processing of a queue, the following commands are available:<br />
● FLUSH<br />
Updates the full text index with the documents in the queue which have already been processed and removes<br />
them from the queue.<br />
● SUSPEND<br />
Suspends the full text index processing queue<br />
● ACTIVATE<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 241
Activates the full text index processing queue if it has been suspended<br />
To manipulate the processing of a queue:<br />
1. Identify which queue process you want to manipulate by using the monitoring view M_FULLTEXT_QUEUES.<br />
For information about the specific content of the view, see <strong>SAP</strong> <strong>HANA</strong> System Tables and Monitoring Views.<br />
2. Use the ALTER FULLTEXT INDEX statement to flush, suspend, or reactivate the queue.<br />
Use the following syntax:<br />
ALTER FULLTEXT INDEX FLUSH|SUSPEND|ACTIVATE QUEUE<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> System Tables and Monitoring Views: M_FULLTEXT_QUEUES<br />
11.1.3 Text Analysis<br />
The text analysis provides a vast number of possible entity types and analysis rules for many industries in 20<br />
languages. However, you do not have to deal with this complexity when analyzing your individual set of<br />
documents. The language modules included with the software contain system dictionaries and provide an<br />
extensive set of predefined entity types. The extraction process can extract entities using these lists of specific<br />
entities. It can also discover new entities using linguistic models. Extraction classifies each extracted entity by<br />
entity type and presents this metadata in a standardized format.<br />
The following data types are enabled for text analysis: NVARCHAR, VARCHAR, and STRING.<br />
The following text analysis options are delivered by <strong>SAP</strong>:<br />
Table 10: Options<br />
Name of Option Description<br />
LINGANALYSIS_BASIC This option provides the following language processing<br />
capabilities for linguistic analysis of unstructured data:<br />
● Segmentation - the separation of input text into its elements<br />
LINGANALYSIS_STEMS This option provides the following language processing<br />
capabilities for linguistic analysis of unstructured data:<br />
● Segmentation - the separation of input text into its elements<br />
● Stemming - the identification of word stems, or dictionary<br />
forms<br />
LINGANALYSIS_FULL This option provides the following language processing<br />
capabilities for linguistic analysis of unstructured data:<br />
● Segmentation - the separation of input text into its elements<br />
● Stemming - the identification of word stems, or dictionary<br />
forms<br />
● Tagging - the labeling of words' parts of speech<br />
EXTRACTION_CORE This option extracts entities of interest from unstructured text,<br />
e.g. people, organizations, places, and other parties described in<br />
the document.<br />
242<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Name of Option Description<br />
In most use cases, this option is sufficient.<br />
EXTRACTION_CORE_VOICEOFCUSTOMER Voice of the customer content includes a set of entity types and<br />
rules that address requirements for extracting customer<br />
sentiments and requests. You can use this content to retrieve<br />
specific information about your customers' needs and<br />
perceptions when processing and analyzing text. The option<br />
involves complex linguistic analysis and pattern matching that<br />
includes processing parts of speech, syntactic patterns, negation,<br />
and so on, to identify the patterns to be extracted.<br />
Voice of the customer content is supported for these languages:<br />
● English<br />
● French<br />
● German<br />
● Spanish<br />
To use the text analyzing function, create a full text index on the column which contains your texts with the<br />
following parameters:<br />
TEXT ANALYSIS ON<br />
CONFIGURATION ''<br />
Note:<br />
Technical names of the options are case-sensitive.<br />
If your tables contain a language indicator, you should enter the name of the column:<br />
LANGUAGE COLUMN <br />
If no language is specified, EN will be used by default.<br />
Once the indexing is started, the text analysis runs in the background. Depending on the number and size of the<br />
texts, one analysis can take hours. To check the status of the text analysis, you can use the default monitoring<br />
view FULLTEXT_INDEXES.<br />
For each full text index, the system creates an additional table with the naming $TA_ within the<br />
same schema which contains the source table.<br />
This table stores the extracted entities and the analysis results. You can use this table to build joins with other<br />
search enabled views, for example to use it for interactive navigation or auto-completion in search input fields.<br />
You can find detailed information on this table under Structure of the $TA Table.<br />
To keep track of deletions in the source table, the keys in the $TA table need to be aligned to the keys of the<br />
source table. To do this, use the following SQL statement:<br />
ALTER TABLE ""."$TA_INDEX_NAME" ADD CONSTRAINT COMMAND<br />
FOREIGN KEY("key_1", "key_2", "key_n") REFERENCES "".""("key_1","key_2","key_n") ON DELETE CASCADE<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 243
Related Links<br />
For triggering the text analysis using the option EXTRACTION_CORE, specify the following additional<br />
parameters for the full text index:<br />
TEXT ANALYSIS ON<br />
CONFIGURATION 'EXTRACTION_CORE'<br />
LANGUAGE COLUMN LANG<br />
ALTER TABLE "MY_SCHEMA"."$TA_CUSTOMER_INDEX" ADD CONSTRAINT ALTER_COMMAND<br />
FOREIGN KEY("KEY_1", "KEY_2") REFERENCES<br />
"MY_SCHEMA"."CUSTOMERS"("KEY_1","KEY_2") ON DELETE CASCADE<br />
Text Data Processing Language Reference <strong>Guide</strong><br />
This guide describes in detail the standard extraction content and the linguistic analysis<br />
Structure of the $TA Table<br />
The table $TA_ is generated automatically after triggering the index creation. The table is built<br />
from the key fields of the source table, additional key fields TA_RULE and TA_COUNTER, and 8 additional fields.<br />
● Key fields of the source table<br />
● Name of the analyzed column<br />
● Entity type, for example DATE or NOUN_GROUP<br />
● Entity value, for example October 29, 2010 or horizontal stabilizer<br />
● Normalized entity value, if available, for example 2010-10-29<br />
Table 11: Structure of TA table<br />
Column ID Key Description Data Type<br />
<br />
Yes In order to support a foreign key definition<br />
linking from the $TA table to its source table,<br />
the $TA table has to use exactly the same key<br />
columns of its source table (in data type and<br />
ID).<br />
The $TA table includes all keys from the<br />
source table.<br />
TA_RULE Yes Stores the rule package that yielded the<br />
token. This is also required to distinguish<br />
between LXP output and output from the<br />
entity extraction.<br />
TA_COUNTER Yes The token counter counts all tokens across<br />
244<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
the document. The order is only unique for a<br />
same as in source table<br />
NVARCHAR(200)<br />
BIGINT<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Column ID Key Description Data Type<br />
given processing type (hence the previous<br />
attribute as key).<br />
TA_TOKEN - Term or entity - depending on processing<br />
type.<br />
TA_LANGUAGE - Usually, the document's language is stated in<br />
the source table. In rare cases where this is<br />
not true, the language code is stored here. As<br />
there is no support for multi-language<br />
documents, the language code is identical for<br />
all result records of a document.<br />
TA_TYPE - The token type contains the linguistic or<br />
semantic type of the token; for instance<br />
"noun" (if option = LINGANALYSIS_*) or<br />
"company" (if option = EXTRACTION_*).<br />
TA_NORMALIZED - Stores a normalized representation of the<br />
token. This becomes relevant e.g. for German<br />
with umlauts, or ß/ss. Normalization with<br />
regards to capitalization would not be as<br />
important as to justify this column.<br />
TA_STEM - Stores the linguistic stemming information,<br />
e.g. the singular nominative for nouns, or the<br />
indicative for verbs. If text analysis yields<br />
several stems, only the first stem will be<br />
stored, assuming this to be the best match.<br />
TA_PARAGRAPH - Stores the number of all paragraphs in the<br />
document.<br />
TA_SENTENCE - Stores the number of all sentences in a<br />
document.<br />
TA_CREATED_AT - Stores the creation time. Used for mere<br />
administrative information; e.g. for<br />
reorganizing purposes.<br />
The $TA table can be modified like any other table, but it cannot be partitioned.<br />
You can add additional columns to this table, e.g. with a statement like ALTER TABLE<br />
NVARCHAR(250)<br />
NVARCHAR(2)<br />
NVARCHAR(100)<br />
NVARCHAR(250)<br />
NVARCHAR(300)<br />
INTEGER<br />
INTEGER<br />
TIMESTAMP<br />
"TA"."$TA_SOURCE_TEXT_TA" ADD(C INTEGER GENERATED ALWAYS AS 1). In this example, the value 1 will be<br />
written to only existing rows in the new column C. The new column will not be filled automatically in delta updates.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 245
Note:<br />
If the source table has a field name identical to one of the default fields from the $TA table, you will receive<br />
an error message after the CREATE FULTTEXT INDEX statement informing you to rename the field of the<br />
source table. After you rename the corresponding field, you can execute the CREATE FULLTEXT INDEX<br />
statement again.<br />
11.1.4 Dropping Full Text Indexes<br />
If you want to delete a full text index that you manually created, for example, because it is referenced only rarely<br />
or preprocessing is too time-consuming, you can drop the full text index. For TEXT or SHORTTEXT full text<br />
indexes, you cannot drop the full text index; instead, you must delete the related column in the table.<br />
You also need to drop full text indexes when adding or removing index parameters. As parameters cannot be<br />
added to or removed from an existing full text index, if you want to change parameters, you must first drop the full<br />
text index and then create a new index with the new parameters.<br />
To drop a full text index, you use the DROP FULLTEXT INDEX statement:<br />
DROP FULLTEXT INDEX <br />
Related Links<br />
Note: Before you can drop a full text index, you must remove the relationship between the source table<br />
and any existing $TA tables (for text analysis). To do so, use the following statement:<br />
ALTER TABLE SCHEMA DROP <br />
The name constraint must be the same as originally used when adding the constraint. For more<br />
information, see Text Analysis.<br />
Altering Full Text Index Parameters [page 246]<br />
You can alter a full text index after it is created. Altering an index includes changing the values of the<br />
parameters and altering the parameters by replacing the index.<br />
Text Analysis [page 242]<br />
11.1.5 Altering Full Text Index Parameters<br />
You can alter a full text index after it is created. Altering an index includes changing the values of the parameters<br />
and altering the parameters by replacing the index.<br />
● To alter the parameters of a full text index, use the ALTER FULLTEXT INDEX statement.<br />
You can only use this statement to alter the following parameters:<br />
○ Fuzzy search index<br />
○ Phrase index ratio<br />
Example syntax:<br />
ALTER FULLTEXT INDEX <br />
PHRASE INDEX RATIO <br />
FUZZY SEARCH INDEX <br />
● To alter any other parameter, you must replace the existing full text index as follows:<br />
246<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
a) Delete the existing full text index by using the DROP FULLTEXT INDEX statement.<br />
b) Create a new index using the new parameter values.<br />
Related Links<br />
Creating Full Text Indexes [page 235]<br />
When you create a TEXT or SHORTTEXT column in a table, <strong>SAP</strong> <strong>HANA</strong> automatically creates a corresponding<br />
full text index. However, for columns of other data types, you must manually create and define any necessary<br />
full text indexes.<br />
Synchronization [page 240]<br />
Full text indexes in a <strong>SAP</strong> <strong>HANA</strong> database must be created and updated in synchronization with the<br />
corresponding columns. This synchronization can be either synchronous or asynchronous.<br />
Queues [page 240]<br />
The queue is a mechanism used to enable a full text index to operate asynchronously. This means that when<br />
you insert new entries into the column, the text is not made available in the column until it is preprocessed.<br />
Full Text Index Parameters [page 247]<br />
The content and behavior of a full text index is configured by the use of both default and user-specified<br />
parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.<br />
11.1.6 Full Text Index Parameters<br />
The content and behavior of a full text index is configured by the use of both default and user-specified<br />
parameters. To view the configuration of a full text index, you use the SYS.FULLTEXT_INDEXES view.<br />
In <strong>SAP</strong> <strong>HANA</strong>, full text indexes are configured using the following parameters:<br />
Parameter Data<br />
Type<br />
SCHEMA_NAM<br />
E<br />
NVARCH<br />
AR(256)<br />
TABLE_NAME NVARCH<br />
AR(256)<br />
TABLE_OID BIGINT<br />
INDEX_NAME NVARCH<br />
AR(256)<br />
INDEX_OID BIGINT<br />
LANGUAGE_C<br />
OLUMN<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
NVARCH<br />
AR(256)<br />
Default<br />
(TEXT)<br />
Default<br />
(SHORTTEXT)<br />
None None None<br />
Default (Manually<br />
Created)<br />
Description<br />
Specifies the schema name<br />
Specifies the table name<br />
Specifies the object ID of the<br />
table<br />
Specifies the name of the full<br />
text index<br />
Specifies the object ID of the<br />
full text index<br />
Specifies the language used for<br />
analyzing the document. If no<br />
language is specified,<br />
automatic language detection is<br />
performed. The detected<br />
language is stored with the<br />
TEXT_AE attribute.<br />
With this option, you can refer<br />
to a column of the same<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 247
Parameter Data<br />
Type<br />
MIME_TYPE_<br />
COLUMN<br />
LANGUAGE_D<br />
ETECTION<br />
FAST_PREPR<br />
OCESS<br />
248<br />
NVARCH<br />
AR(256)<br />
NVARCH<br />
AR(5000<br />
)<br />
Default<br />
(TEXT)<br />
Default<br />
(SHORTTEXT)<br />
None None None<br />
EN EN EN<br />
TINYINT ON ON ON<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
Default (Manually<br />
Created)<br />
Description<br />
database table in which the<br />
language for the document is<br />
stored. The column is read by<br />
the queue.<br />
languageColumn in basetable<br />
should be of type NVARCHAR/<br />
VARCHAR(m) where m>=2<br />
when not NULL:<br />
table(tableoid).hasColumn(lang<br />
uageColumn)<br />
This column holds a format/<br />
mimetype indicator (for plain<br />
text, the encoding can also be<br />
specified), e.g. ('text/<br />
plain:CP-1252','PDF','MS_WOR<br />
D 3.0',..).<br />
'FORMAT' is handled in the<br />
same way as 'LANGUAGE'.<br />
when not NULL:<br />
table(tableoid).hasColumn(mi<br />
meTypeColumn)<br />
Specifies the set of languages<br />
to be considered for automatic<br />
language detection. If reliable<br />
language detection cannot be<br />
performed, the first language in<br />
the list will be used as the<br />
default language.<br />
This option is used to limit the<br />
languages for text analysis. The<br />
parameter is currently ignored<br />
by text analysis. when not<br />
NULL: for each language L in<br />
languageDetection: L in (select<br />
language from<br />
SYS.M_TEXT_ANALYSIS_LANG<br />
UAGES)<br />
Specifies if fast preprocessing<br />
should be performed. With fast<br />
preprocessing the detected<br />
language is always the default<br />
language.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Parameter Data<br />
Type<br />
FUZZY_SEAR<br />
CH_INDEX<br />
SEARCH_ONL<br />
Y<br />
IS_EXPLICI<br />
T<br />
FLUSH_AFTE<br />
R_DOCUMENT<br />
S<br />
FLUSH_EVER<br />
Y_MINUTES<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
Default<br />
(TEXT)<br />
Default<br />
(SHORTTEXT)<br />
TINYINT OFF OFF OFF<br />
Default (Manually<br />
Created)<br />
TINYINT OFF ON for LOB-types<br />
OFF, otherwise ON<br />
TINYINT 0 0 1<br />
INTEGER N/A N/A<br />
INTEGER N/A N/A<br />
Description<br />
If this option is activated,<br />
linguisitic analysis is skipped.<br />
Only a simple tokenizer is used.<br />
This does not work for<br />
languages which do not use<br />
spaces as word separators. The<br />
fast analyzer cannot handle<br />
binary documents.<br />
If this option is enabled, a<br />
special index is created for the<br />
fuzzy search. This index<br />
accelerates the fuzzy search<br />
but uses additional memory.<br />
If set to ON, you cannot<br />
reconstruct original content or<br />
show the document in its<br />
original formatting when using<br />
the highlight function. With this<br />
setting, the text attributes do<br />
not store any DAFs, that<br />
means, it is not possible to<br />
retrieve the HTML-converted or<br />
original data from the text<br />
attribute. The document will,<br />
however, use less memory.<br />
If the text attribute is created<br />
via a manually created full text<br />
index, the source attribute that<br />
contains the original data is not<br />
affected by this setting.<br />
Specifies whether the full text<br />
index was manually created<br />
(also known as explicit). By<br />
default, manually created full<br />
text indexes use ASYNC<br />
synchronization.<br />
Specifies when asynchronous<br />
full text indexes are flushed.<br />
The specified value cannot be<br />
negative.<br />
Specifies when asynchronous<br />
full text indexes are flushed.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 249
Parameter Data<br />
Type<br />
CONFIGURAT<br />
ION<br />
INTERNAL_C<br />
OLUMN_NAME<br />
PHRASE_IND<br />
EX_RATIO<br />
TEXT<br />
ANALYSIS<br />
250<br />
NVARCH<br />
AR(5000<br />
)<br />
NVARCH<br />
AR(512)<br />
Default<br />
(TEXT)<br />
Default<br />
(SHORTTEXT)<br />
None None None<br />
FLOAT 0.0 0.0 (0.2 if<br />
length
Parameter Data<br />
Type<br />
Default<br />
(TEXT)<br />
Default<br />
(SHORTTEXT)<br />
Default (Manually<br />
Created)<br />
Description<br />
parameter is automatically set<br />
to OFF.<br />
Text analysis can extract<br />
entities such as persons,<br />
products, or places, from<br />
documents and thus enrich the<br />
set of structured information in<br />
<strong>SAP</strong> <strong>HANA</strong>. You can use these<br />
additional attributes, which are<br />
stored in a new table, when<br />
creating models (views) for<br />
analytics and search scenarios<br />
to enable improved analytics<br />
and search in <strong>SAP</strong> <strong>HANA</strong>.<br />
For more information, see Text<br />
Analysis [page 242].<br />
Memory Consumption of Full Text Index Parameters<br />
In <strong>SAP</strong> <strong>HANA</strong>, certain full text index parameters can have a significant impact on memory consumption based on<br />
how they are defined.<br />
The following full text index parameters can have a significant impact on memory consumption:<br />
Parameter Memory Impact Details<br />
PHRASE_INDEX_RATIO If the value is greater than 0.0, then there is additional<br />
memory overhead. The maximum memory<br />
consumption is the memory consumption of the full<br />
text index multiplied by the parameter value.<br />
FUZZY_SEARCH_INDEX To increase response times for fuzzy search, when<br />
enabled, this parameter creates additional in-memory<br />
structures. For text-type columns, fuzzy search<br />
indexes require approx. 10% of the memory size of the<br />
column.<br />
TEXT ANALYSIS If set to ON, an additional table is created for storing<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
structured data extracted from the source text for text<br />
analysis. The amount of extracted data depends on the<br />
data in the source column, the text analysis rules, and<br />
the structure of the results. In certain cases, the<br />
memory consumption of the extracted data could<br />
exceed the memory consumption of the source data.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 251
11.2 Building SQL Search Queries<br />
In column-oriented tables, you can perform searches using the SQL SELECT statement.<br />
Before building SQL search queries, the following prerequisites must be met:<br />
● The tables you want to search are column-oriented.<br />
● You have created any required views for the tables you want to search.<br />
● You have created any required full text indexes for the columns you want to search.<br />
<strong>SAP</strong> <strong>HANA</strong> supports the standard SQL search syntax and functions for search queries on nearly all visible data<br />
types. You build SQL queries using the SELECT statement, as in the following example:<br />
SELECT * FROM Contacts WHERE ID=1<br />
However, in <strong>SAP</strong> <strong>HANA</strong>, columns of large object types and text have additional requirements. To enable search on<br />
columns of these types, you must ensure the following requirements are met:<br />
● Full text indexes have been created for the search-relevant columns. For columns of type TEXT and<br />
SHORTTEXT, this is done automatically.<br />
● Search queries on the columns use the CONTAINS predicate.<br />
For large object types and text, you build SQL queries using the SELECT statement and CONTAINS predicate, as<br />
in the following example:<br />
SELECT * FROM Documents WHERE CONTAINS (*,'Comment')<br />
To build a search query, proceed as follows:<br />
1. Use the SQL SELECT statement and specify the table or view and column you want to search. If required,<br />
include the CONTAINS predicate.<br />
2. If required, specify scalar functions for the search.<br />
3. Specify the search terms and, optionally, the search type (EXACT, LINGUISTIC, or FUZZY).<br />
Note: If you do not specify a search type, by default, the search query is performed as an exact<br />
search.<br />
For further examples of the syntax used with the SELECT statement, see <strong>SAP</strong> <strong>HANA</strong> SQL Reference<br />
Manual.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> SQL Reference Manual: SELECT<br />
11.2.1 Search Queries with CONTAINS<br />
In <strong>SAP</strong> <strong>HANA</strong>, you can search one or multiple columns by creating a query that includes the CONTAINS predicate.<br />
In <strong>SAP</strong> <strong>HANA</strong>, a search query with CONTAINS has a look and feel similar to common Internet search engines.<br />
252<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
The CONTAINS predicate is optional for search queries on columns of most data types; however, for large object<br />
types and text, this predicate is mandatory. You can build a search query with the CONTAINS predicate as<br />
follows:<br />
SELECT * FROM <br />
WHERE CONTAINS ((, , ), )<br />
When you specify the CONTAINS predicate, <strong>SAP</strong> <strong>HANA</strong> runs the following internal checks:<br />
● <strong>SAP</strong> <strong>HANA</strong> checks if the query contains one or more terms. If the query contains multiple terms, the terms<br />
are tokenized and concatenated.<br />
● <strong>SAP</strong> <strong>HANA</strong> checks whether the query is to be run on one or more columns. If you only specify one column, to<br />
optimize the search, additional processes are skipped and the query is run on the single column. If you specify<br />
a wildcard, and therefore possibly numerous columns, <strong>SAP</strong> <strong>HANA</strong> automatically determines which columns<br />
are relevant for the search query.<br />
After the checks are performed, <strong>SAP</strong> <strong>HANA</strong> builds and runs an internal query on the relevant columns only.<br />
Note:<br />
If a column has a full text index assigned, <strong>SAP</strong> <strong>HANA</strong> will automatically search on the index rather than on<br />
the original column.<br />
Determination of Search-Relevant Columns<br />
You can specify the search-relevant columns either at the creation of the view or directly for the query. <strong>SAP</strong> <strong>HANA</strong><br />
determines which relevant columns to search based on the following hierarchy:<br />
1. You specify a list of columns within the CONTAINS predicate. Even if a list of columns has been defined for<br />
the view, it is overridden by the columns stated in the query.<br />
2. If you enter an asterisk (*) instead of a column list but you specified a list of relevant columns when creating<br />
the view, this list is used for the query.<br />
3. If you enter an asterisk (*) and no list was provided when the view was created, all visible columns of the view<br />
or table are considered as search-relevant.<br />
For information about creating views, see Creating Views in the <strong>SAP</strong> <strong>HANA</strong> Administration <strong>Guide</strong>.<br />
Search Operators and Syntax<br />
With the CONTAINS predicate, <strong>SAP</strong> <strong>HANA</strong> supports the following search operators:<br />
● OR<br />
Matches are returned that contain at least one of the terms joined by the OR operator.<br />
● - (minus)<br />
With a minus sign, <strong>SAP</strong> <strong>HANA</strong> searches in columns for matches that do not contain the term immediately<br />
following the minus sign.<br />
● " " (quotation marks)<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 253
Terms within the quotation marks are not tokenized and are handled as a string. Therefore, all search<br />
matches must be exact.<br />
Note: If you enter multiple search terms, the AND operator is automatically interpreted. Therefore, you do<br />
not need to specify it.<br />
For more information about the unique syntax requirements of the CONTAINS predicate, see the <strong>SAP</strong> <strong>HANA</strong> SQL<br />
Reference.<br />
Scalar Functions<br />
For search queries using the CONTAINS predicate, you can use different scalar functions to either return<br />
additional information about the results of your search queries or enhance how the results are displayed. These<br />
functions include SNIPPET, HIGHLIGHTED, and SCORE.<br />
Limitations<br />
The following limitations apply to search queries using the CONTAINS predicate:<br />
● You cannot search on more than one table or view at a time. If more than one table is joined in the SELECT<br />
statement, then all columns mentioned in the CONTAINS predicate must come from only one of the tables.<br />
● You cannot enter a minus (-) search operator directly after OR.<br />
● Brackets are not supported as search operators.<br />
● Searches using the CONTAINS predicate do not consider non-physical columns, such as calculated columns,<br />
as search-relevant because these columns are created during the search and, therefore, are not available<br />
when <strong>SAP</strong> <strong>HANA</strong> internally checks the CONTAINS search query.<br />
● The CONTAINS predicate only works on column-oriented tables.<br />
● If you specify multiple CONTAINS predicates in the WHERE clause of the SELECT statement, only one of the<br />
predicates is allowed to consist of more than one column in the list of .<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> SQL Reference: CONTAINS Predicate<br />
<strong>SAP</strong> <strong>HANA</strong> Administration <strong>Guide</strong><br />
SNIPPET Function<br />
For search queries using the CONTAINS predicate, you can use the function SNIPPET to return search results<br />
with an excerpt of the text with your search term highlighted in bold. This short text excerpt provides some<br />
context for you to see where and how the term is used in the document.<br />
This function uses the following syntax:<br />
SELECT *, SNIPPET () FROM <br />
WHERE CONTAINS ()<br />
254<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Limitations<br />
The SNIPPET function has the following limitations:<br />
● Only the first search term specified with the CONTAINS predicate is highlighted in the returned text.<br />
● The query result contains only the first hit of the first search term.<br />
● The text excerpt that is displayed with the search term is limited to a string of 12 tokens.<br />
● This function only works on columns of the TEXT data type or columns with a full text index.<br />
HIGHLIGHTED Function<br />
For search queries using the CONTAINS predicate, you can use the function HIGHLIGHTED to return the<br />
content of the found document with your search term highlighted in bold.<br />
Search queries using the HIGHLIGHTED function return the data type NCLOB.<br />
This function uses the following syntax:<br />
SELECT *, HIGHLIGHTED () FROM <br />
WHERE CONTAINS ()<br />
Limitations<br />
The HIGHLIGHTED function has the following limitations:<br />
● Only the first search term specified with the CONTAINS predicate is highlighted in the returned text.<br />
● The query result contains all hits of the first search term.<br />
● This function only works on columns of the TEXT data type or columns with a full text index.<br />
SCORE Function<br />
For search queries using the CONTAINS predicate, you can use the function SCORE to get the score, that means<br />
the relevance, of a record found.<br />
<strong>SAP</strong> <strong>HANA</strong> calculates a score based on the following information:<br />
● The relevance or weighting of attributes in a search using the CONTAINS predicate. The relevance of a hit<br />
depends on the weight of the column that caused the hit. You can specify weights when you create the view or<br />
in the CONTAINS predicate.<br />
● Fuzziness in fuzzy search. The more exact a hit is, the higher the score is.<br />
● Text ranking (TF-IDF).<br />
This function uses the following syntax:<br />
SELECT SCORE (),* FROM <br />
WHERE CONTAINS ()<br />
11.2.2 EXACT Search<br />
An exact search returns records only if the search term or search phrase is contained in the table column exactly<br />
as specified. In the SELECT statement of the search query, you can specify the EXACT search type.<br />
In an exact search, the search engine uses the word dictionary and the phrase index to detect the possible<br />
matches. The search engine then checks whether the words appear and use exactly the same spelling.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 255
● For text columns, the search term must match at least one of the tokenized terms to return a column entry as<br />
a match.<br />
● For string columns, the search term must match the entire string to return a column entry as a match.<br />
Note: For more flexibility in a search query, you can use the supported wildcards % and *. Wildcards are<br />
supported for both text and string columns.<br />
You can perform an exact search by using the CONTAINS predicate with the EXACT option in the WHERE clause<br />
of a SELECT statement. The exact search is the default search type. If you do not specify any search type in the<br />
search query, an exact search will be executed automatically.<br />
SELECT * FROM <br />
WHERE CONTAINS (, , EXACT)<br />
SELECT * FROM <br />
WHERE CONTAINS (, )<br />
--- Exact search will be executed implicitly.<br />
SELECT * FROM <br />
WHERE CONTAINS (, '"cats and dogs"')<br />
--- Phrase search.<br />
11.2.3 LINGUISTIC Search<br />
A linguistic search finds all words that have the same word stem as the search term. It also finds all words for<br />
which the search term is the word stem. In the SELECT statement of the full text search query, you can specify<br />
the LINGUISTIC search type.<br />
When you execute a linguistic search, the system has to determine the stems of the searched terms. It will look up<br />
the stems in the stem dictionary. The hits in the stem dictionary point to all words in the word dictionary that have<br />
this stem<br />
You can call the linguistic search by using the CONTAINS predicate with the LINGUISTIC option in the WHERE<br />
clause of a SELECT statement.<br />
A linguistic search for produced will also find producing and produce.<br />
Limitations<br />
SELECT * FROM <br />
WHERE CONTAINS (
Fuzzy search can be used in various applications, for example:<br />
● Fault-tolerant search in text columns (for example, html or pdf): Search for documents on 'Driethanolamyn'<br />
and find all documents that contain the term 'Triethanolamine'.<br />
● Fault-tolerant search in structured database content: Search for a product called 'coffe krisp biscuit' and find<br />
'Toffee Crisp Biscuits'.<br />
● Fault-tolerant check for duplicate records: Before creating a new customer record in a CRM system, search for<br />
similar customer records and verify that there are no duplicates already stored in the system. When, for<br />
example, creating a new record 'SAB Aktiengesellschaft & Co KG Deutschl.' in 'Wahldorf', the system shall<br />
bring up '<strong>SAP</strong> Deutschland AG & Co. KG' in 'Walldorf' as a possible duplicate.<br />
You can call the fuzzy search by using the CONTAINS predicate with the FUZZY option in the WHERE clause of a<br />
SELECT statement.<br />
Fuzzy Score<br />
SELECT * FROM <br />
WHERE CONTAINS (, , FUZZY (0.8))<br />
Note: You can improve the performance of a fuzzy search on a text column by defining a fuzzy<br />
index at the column. You can define a fuzzy index with the option FUZZY SEARCH INDEX ON in<br />
the CREATE FULLTEXT INDEX statement or in the definition of data type TEXT.<br />
The fuzzy search algorithm calculates a fuzzy score for each string comparison. The higher the score, the more<br />
similar the strings are. A score of 1.0 means the strings are identical. A score of 0.0 means the strings have<br />
nothing in common.<br />
You can request the score in the SELECT statement by using the SCORE() function. You can sort the results of a<br />
query by score in descending order to get the best records first (the best record is the record that is most similar<br />
to the user input). When a fuzzy search of multiple columns is used in a SELECT statement, the score is returned<br />
as an average of the scores of all columns used.<br />
When searching text columns, a TF/IDF (term frequency/inverse document frequency) score is returned by<br />
default instead of the fuzzy score. The fuzzy score influences the TF/IDF calculation, but it is important to keep in<br />
mind that, with TF/IDF, the range of the score values returned is normed to the interval between 0.0 and 1.0, and<br />
the best record always gets a score of 1.0, regardless of its fuzzy score.<br />
The TF/IDF calculation can be disabled so that you get the fuzzy score instead. In particular, this makes sense for<br />
short-text columns containing data such as product names or company names. On the other hand, you should<br />
use TF/IDF for long-text columns containing data such as product descriptions, HTML data, or Word and PDF<br />
documents.<br />
Option spellCheckFactor<br />
There are two use cases for the option spellCheckFactor.<br />
● A) This option allows you to set the score for terms that are not fully equal but that would be a 100% match<br />
because of the internal character standardization used by the fuzzy search.<br />
For example, the terms 'Café' and 'cafe' give a score of 1.0 although the terms are not equal. For some users it<br />
may be necessary to distinguish between both terms.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 257
The decision if two terms are equal is based on the term representation stored in the column dictionary.<br />
Therefore the spellCheckFactor option works differently on string and text columns, as described in the<br />
following sections.<br />
● B) The fuzzy search can return a 100% match for terms that are not identical but can't be differentiated by<br />
the fuzzy-string-compare algorithm.<br />
For example, fuzzy search can't differentiate between terms 'abaca' and 'acaba', for example. In this case, the<br />
spellCheckFactor can be used to avoid a score of 1.0.<br />
When A) and B) are not needed by an application, you can set the spellCheckFactor to 1.0 to disable the feature.<br />
Standardization of Letters and Terms<br />
All characters are replaced by a lowercase character without any diacritics before the fuzzy comparison takes<br />
place. This is called standardization. So it is possible to get a 100% match when comparing two unequal terms,<br />
because the standardization process returned two identical terms.<br />
Standardization Examples<br />
Original Letter Standardized Letter<br />
E e<br />
e e<br />
É e<br />
é e<br />
Ė e<br />
ė e<br />
The letter i is treated differently as it is not standardized to an ı as would be the 'standard' rule.<br />
Original Letter Standardized Letter<br />
I i<br />
İ i<br />
i i<br />
ı i<br />
German umlauts are replaced by two characters.<br />
Original Letter Standardized Letter<br />
Ä ae<br />
258<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Original Letter Standardized Letter<br />
ä ae<br />
Ö oe<br />
ö oe<br />
Ü ue<br />
ü ue<br />
ß ss<br />
Because of this standardization we get high fuzzy scores for common differences in the spelling of words.<br />
Original term Standardized term<br />
müller mueller<br />
Mueller mueller<br />
Cafe cafe<br />
Café cafe<br />
Search on a String Column (VARCHAR, NVARCHAR)<br />
The decision if two strings are the same is based on the string representation that is stored in the dictionary for<br />
that column. The contents of a string column are converted to lowercase characters before they are stored in the<br />
dictionary. Other standardizations are not done.<br />
So it is possible to use the spellCheckFactor option to, for example, distinguish between 'café' and 'cafe'.<br />
CREATE COLUMN TABLE test_spell_check_factor<br />
(<br />
id INTEGER PRIMARY KEY,<br />
s NVARCHAR(255)<br />
);<br />
INSERT INTO test_spell_check_factor VALUES ('1','Muller');<br />
INSERT INTO test_spell_check_factor VALUES ('2','Mueller');<br />
INSERT INTO test_spell_check_factor VALUES ('3','Müller');<br />
INSERT INTO test_spell_check_factor VALUES ('4','Möller');<br />
SELECT SCORE() AS score, id, s<br />
FROM test_spell_check_factor<br />
WHERE CONTAINS(s, 'Müller', FUZZY(0.5, 'spellCheckFactor=0.9'))<br />
ORDER BY score DESC;<br />
DROP TABLE test_spell_check_factor;<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 259
SCORE ID T Description<br />
1.0 3 Müller<br />
0.9 2 Mueller
Option similarCalculationMode<br />
The option similarCalculationMode controls how the similarity of two strings (or, for TEXT attributes, terms) is<br />
calculated.<br />
Score calculation modes<br />
Basically, the similarity of two strings is defined by the number of common characters, wrong characters,<br />
additional characters in the search string and additional characters in the reference string.<br />
There are the following calculation modes:<br />
Table 12: Modes<br />
Mode Impact on wrong<br />
characters<br />
Impact on additional<br />
characters in search<br />
search high high low<br />
compare (default) moderate high high<br />
symmetricsearch high moderate moderate<br />
Note that high impact results in a lower score.<br />
Table 13: Examples with score<br />
Request Reference Compa<br />
re<br />
Search Symmetricsearch<br />
search searching 0.76 0.96 0.86<br />
search search 0.85 0.75 0.75<br />
search searchingforextrater<br />
searchingforextrater<br />
restriallife<br />
searchingforextrater<br />
restriallife<br />
searchingforextrater<br />
restriallife<br />
SQL Examples<br />
Preparations<br />
restriallife<br />
0.0 0.91 0.87<br />
searching 0.0 0.35 0.84<br />
search 0.0 0.24 0.79<br />
searchingforthemea<br />
ningoflife<br />
0.6 0.57 0.6<br />
OP TABLE test_similar_calculation_mode;<br />
CREATE COLUMN TABLE test_similar_calculation_mode<br />
(<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
Impact on additional<br />
characters in table<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 261
);<br />
id INTEGER PRIMARY KEY,<br />
s NVARCHAR(255)<br />
INSERT INTO test_similar_calculation_mode VALUES ('1','stringg');<br />
INSERT INTO test_similar_calculation_mode VALUES ('2','string theory');<br />
INSERT INTO test_similar_calculation_mode VALUES ('3','this is a very very<br />
very long string');<br />
INSERT INTO test_similar_calculation_mode VALUES ('4','this is another<br />
very long string');<br />
similarCalculationMode compare<br />
SELECT TO_INT(SCORE()*100)/100 AS score, id, s<br />
FROM test_similar_calculation_mode<br />
WHERE CONTAINS(s, 'explain string theory', FUZZY(0.5,<br />
'similarCalculationMode=compare'))<br />
ORDER BY score DESC;<br />
Score ID S<br />
0.69 2 string theory<br />
similarCalculationMode search<br />
SELECT TO_INT(SCORE()*100)/100 AS score, id, s<br />
FROM test_similar_calculation_mode<br />
WHERE CONTAINS(s, 'explain string theory', FUZZY(0.5,<br />
'similarCalculationMode=search'))<br />
ORDER BY score DESC;<br />
Score ID S<br />
0.68 4 this is another very long string<br />
0.66 3 this is a very very very long string<br />
0.65 2 string theory<br />
similarCalculationMode symmetricsearch<br />
SELECT TO_INT(SCORE()*100)/100 AS score, id, s<br />
FROM test_similar_calculation_mode<br />
WHERE CONTAINS(s, 'explain string theory', FUZZY(0.5,<br />
'similarCalculationMode=symmetricsearch'))<br />
ORDER BY score DESC;<br />
Score ID S<br />
0.85 2 string theory<br />
0.71 1 stringg<br />
0.61 4 this is another very long string<br />
0.58 3 this is a very very very long string<br />
262<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Supported Data Types<br />
Fuzzy search works out-of-the-box on the following column-store data types:<br />
● TEXT<br />
● SHORTTEXT<br />
● VARCHAR, NVARCHAR<br />
● DATE<br />
● All data types with a full-text index<br />
String Types<br />
String types support a basic fuzzy string search. The values of a column are compared with the user input, using<br />
the fault-tolerant fuzzy string comparison.<br />
When working with string types, the fuzzy string comparison always compares the full strings. If searching with<br />
'<strong>SAP</strong>', for example, a record such as '<strong>SAP</strong> Deutschland AG & Co. KG' gets a very low score, because only a very<br />
small part of the string is equal (3 of 27 characters match).<br />
A fuzzy search on string types is an alternative to a non-fault-tolerant SQL statement such as<br />
SELECT ... FROM products WHERE product_name = 'coffe krisp biscuit' ...<br />
which would not return any results because of the spelling errors.<br />
Supported SQL data types are<br />
● VARCHAR<br />
● NVARCHAR<br />
It is possible to speed up the fuzzy search by creating additional data structures, which are used for faster<br />
calculation of the fuzzy score. These data structures exist in the memory only, so no additional disk space is<br />
required.<br />
To get the best response times possible, you should enable the fast fuzzy search structures for all database<br />
columns that have a high load of fuzzy searches, and for all database columns that are used in performance-<br />
critical queries.<br />
Text Types<br />
Text types support a more sophisticated kind of fuzzy search. Texts are tokenized (split into terms) and the fuzzy<br />
comparison is done term by term.<br />
For example, when searching with '<strong>SAP</strong>', a record such as '<strong>SAP</strong> Deutschland AG & Co. KG' gets a high score,<br />
because the term '<strong>SAP</strong>' exists in both texts. A record such as '<strong>SAP</strong>PHIRE NOW Orlando' gets a lower score,<br />
because '<strong>SAP</strong>' is only a part of the longer term '<strong>SAP</strong>PHIRE' (3 of 8 characters match).<br />
A fuzzy search in text columns replaces non-fault-tolerant statements such as<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 263
SELECT ... FROM documents WHERE doc_content LIKE '% Driethanolamyn %' ...<br />
Supported SQL data types are<br />
● TEXT<br />
● SHORTTEXT<br />
● Full-text index<br />
A full-text index is an additional index structure that can be defined for non-text columns to add text search<br />
features. Supported column types are, for example, NCLOB and NVARCHAR.<br />
It is possible to speed up the fuzzy search by creating additional data structures, which are used for faster<br />
calculation of the fuzzy score. These data structures exist in the memory only, so no additional disk space is<br />
required. To create the additional structures, use the flag 'fast_fuzzy_search' when creating a TEXT or<br />
SHORTTEXT column or when creating a full-text index.<br />
To get the best response times possible, you should enable the fast fuzzy search structures for all database<br />
columns that have a high load of fuzzy searches and for all database columns that are used in performance-<br />
critical queries.<br />
Other Types<br />
Fuzzy search is available for the SQL type DATE. A fuzzy search on date values checks for date-specific errors<br />
such as dates that lie within a given range of days, or dates where the month and day have been interchanged (for<br />
example, American versus British date format).<br />
It is not possible to create additional data structures for date types to speed up the search. The queries run with<br />
optimal performance without any database tuning.<br />
Syntax<br />
You can call the fuzzy search by using the CONTAINS() function with the FUZZY() option in the WHERE clause of a<br />
SELECT statement.<br />
Basic example without additional search options<br />
SELECT SCORE() AS score, *<br />
FROM documents<br />
WHERE CONTAINS(doc_content, 'Driethanolamyn', FUZZY(0.8))<br />
ORDER BY score DESC;<br />
Example with additional search options<br />
Additional search options that change the default behavior of the fuzzy search can be specified as additional<br />
string parameters in the FUZZY() function.<br />
SELECT SCORE() AS score, *<br />
FROM documents<br />
WHERE CONTAINS(doc_content, 'Driethanolamyn', FUZZY(0.8, 'option1=value1,<br />
264<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
option2=value2'))<br />
ORDER BY score DESC;<br />
The search options are specified as a comma-separated list of key-value pairs.<br />
Available Fuzzy Search Options<br />
Note that some data types in the table below are data-type combinations.<br />
● Text: SQL types TEXT and SHORTTEXT and any columns that have an additional full-text index<br />
● String: SQL types VARCHAR and NVARCHAR<br />
● Date: SQL type DATE<br />
Table 14: Available Fuzzy Search Options<br />
Name of Option Short<br />
Name<br />
textSearch ts fulltext,<br />
Range Defa<br />
ult<br />
compare<br />
fullte<br />
emptyScore es 0.0..1.0 not<br />
similarCalculatio<br />
nMode<br />
spellCheckFacto<br />
r<br />
abbreviationSimi<br />
larity<br />
bestMatchingTo<br />
kenWeight<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
scm search,<br />
compare,<br />
symmetri<br />
csearch<br />
xt<br />
set<br />
comp<br />
are<br />
Applies to<br />
Types<br />
Text, String,<br />
Date<br />
Text, String,<br />
Date<br />
Description<br />
Switches between full-text search with TF/IDF<br />
score and duplicate search with fuzzy score.<br />
For more information, see Option textSearch<br />
[page 289].<br />
Defines how an empty and a non-empty value<br />
shall match.<br />
Text, String Defines how the score is calculated for a<br />
comparison of strings (or terms in a Text<br />
column).<br />
For more information, see Option<br />
similarCalculationMode [page 261] .<br />
scf 0.0..1.0 0.9 Text, String Sets the score for strings that get a fuzzy score of<br />
abs 0.0..1.0 0.0 Text<br />
bmtw 0.0..1.0 0 Text<br />
1.0 but are not fully equal.<br />
For more information, see Option<br />
spellCheckFactor [page 257].<br />
Activates abbreviation similarity and sets the<br />
score.<br />
For more information, see Option<br />
abbreviationSimilarity [page 287].<br />
Influences the score, shifts total score value<br />
between best token score values and root mean<br />
square of score values.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 265
Name of Option Short<br />
Name<br />
considerNonMat<br />
chingTokens<br />
Range Defa<br />
ult<br />
cnmt max, min,<br />
all, input,<br />
table<br />
max Text<br />
minTextScore mts 0.0..1.0 0.0 Text<br />
andSymmetric as on,off off Text<br />
andThreshold at 0.0..1.0 1.0 Text<br />
termMappingTa<br />
ble<br />
termMappingLis<br />
tId<br />
tmt not<br />
set<br />
Applies to<br />
Types<br />
Text<br />
tmli Text<br />
stopwordTable st not<br />
set<br />
Text<br />
stopwordListId sli Text<br />
266<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
Description<br />
For more information, see Fuzzy Multi-Token<br />
Search on Text Columns [page 282].<br />
Influences the score, defines the number of<br />
terms used for score calculation.<br />
For more information, see Fuzzy Multi-Token<br />
Search on Text Columns [page 282].<br />
Minimum score of a TEXT field; if not reached,<br />
the record will not be part of the result.<br />
For more information, see Option minTextScore<br />
[page 288].<br />
Activates a symmetric AND content search.<br />
For more information, see Fuzzy Multi-Token<br />
Search with Soft AND [page 285].<br />
Activates a 'soft AND' and determines the<br />
percentage of the tokens that need to match.<br />
For more information, see Fuzzy Multi-Token<br />
Search with Soft AND [page 285].<br />
Activates the term mappings.<br />
For more information, see Fuzzy Search with<br />
Term Mappings [page 295].<br />
Activates the term mappings.<br />
For more information, see Fuzzy Multi-Token<br />
Search with Soft AND [page 285].<br />
Activates the stopwords.<br />
For more information, see Fuzzy Search with<br />
Stopwords.<br />
Activates the stopwords.<br />
For more information, see Fuzzy Search with<br />
Stopwords.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Name of Option Short<br />
Name<br />
maxDateDistanc<br />
e<br />
Range Defa<br />
ult<br />
mdd 0..100 0 Date<br />
Applies to<br />
Types<br />
Description<br />
Specifies the allowed date distance when using<br />
fuzzy search on dates.<br />
For more information, see Fuzzy Search on DATE<br />
Columns [page 298].<br />
For a list of all allowed search parameter combinations, see Option textSearch [page 289].<br />
Support Information<br />
Memory Usage<br />
Currently, all data structures for the fuzzy search share a common 'Pool/FuzzySearch' allocator.<br />
Statistics can be obtained through the system view M_HEAP_MEMORY.<br />
SELECT * FROM sys.m_heap_memory WHERE category LIKE '%FuzzySearch%'<br />
Activating the Trace in the <strong>SAP</strong> <strong>HANA</strong> Studio<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, open the Administration perspective by double-clicking your system name in the<br />
navigation pane.<br />
2. Select the Diagnosis Files tab and choose Configure in the right corner, as shown below.<br />
3. To configure the trace targets, choose Show All Components and filter for fuzzysearch, as shown below.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 267
To get basic tracing data with information for every search, set the trace level to INFO.<br />
To get detailed information for every search, set the trace level to DEBUG.<br />
Note: Note that DEBUG information cannot be read by end users and should be used for support<br />
issues only.<br />
The default name for the trace file is indexserver_$host_$port.000.trc.<br />
Basic Examples<br />
Speeding Up the Fuzzy Search<br />
You can speed up the fuzzy search for all SQL types except DATE by creating a special data structure called fuzzy<br />
search index. The additional data structures increase the total memory footprint of the loaded table. In<br />
unfavorable cases, the memory footprint of the column can double.<br />
268<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
TEXT and SHORTTEXT<br />
TEXT and SHORTTEXT columns offer the option 'FUZZY SEARCH INDEX' to enable and disable the additional data<br />
structures.<br />
When creating a table:<br />
CREATE COLUMN TABLE mytable<br />
(<br />
id INTEGER PRIMARY KEY,<br />
col1 TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON,<br />
col2 SHORTTEXT(100) FUZZY SEARCH INDEX ON<br />
);<br />
Full-Text Index<br />
A full-text index offers the option 'FUZZY SEARCH INDEX' to enable and disable the additional data structures.<br />
When creating a full-text index:<br />
CREATE COLUMN TABLE mytable<br />
(<br />
col1 NVARCHAR(2000)<br />
);<br />
CREATE FULLTEXT INDEX myindex ON mytable(col1)<br />
FUZZY SEARCH INDEX ON<br />
FAST PREPROCESS ON;<br />
This can be changed at a later point in time by using the ALTER FULLTEXT INDEX command:<br />
ALTER FULLTEXT INDEX myindex FUZZY SEARCH INDEX OFF;<br />
VARCHAR and NVARCHAR<br />
VARCHAR and NVARCHAR columns also offer the option 'FUZZY SEARCH INDEX' to enable and disable the<br />
additional data structures.<br />
When creating a table:<br />
CREATE COLUMN TABLE mytable<br />
(<br />
id INTEGER PRIMARY KEY,<br />
col1 VARCHAR(100) FUZZY SEARCH INDEX ON,<br />
col2 NVARCHAR(100) FUZZY SEARCH INDEX ON<br />
);<br />
Additional performance improvements are possible when creating database indexes on the columns.<br />
CREATE INDEX myindex1 ON mytable(col1);<br />
CREATE INDEX myindex2 ON mytable(col2);<br />
The state of the fuzzy search index can be changed at a later point in time by using the ALTER TABLE statement.<br />
ALTER TABLE mytable ALTER<br />
(<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 269
col1 VARCHAR(100) FUZZY SEARCH INDEX OFF,<br />
col2 NVARCHAR(100)<br />
);<br />
The view SYS.TABLE_COLUMNS shows the current state of the fuzzy search index. When working with attribute<br />
views, this information is also visible in SYS.VIEW_COLUMNS.<br />
SELECT column_name, data_type_name, fuzzy_search_index<br />
FROM table_columns<br />
WHERE table_name = 'MYTABLE';<br />
Fuzzy Search on One Column<br />
1. Create the data.<br />
CREATE COLUMN TABLE companies<br />
(<br />
id INTEGER PRIMARY KEY,<br />
companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO companies VALUES (1, '<strong>SAP</strong> Corp');<br />
INSERT INTO companies VALUES (2, '<strong>SAP</strong> in Walldorf Corp');<br />
INSERT INTO companies VALUES (3, 'A<strong>SAP</strong>');<br />
INSERT INTO companies VALUES (4, 'A<strong>SAP</strong> Corp');<br />
INSERT INTO companies VALUES (5, 'B<strong>SAP</strong> orp');<br />
INSERT INTO companies VALUES (6, 'IBM Corp');<br />
2. Perform the search on one column.<br />
SELECT SCORE() AS score, * FROM companies<br />
WHERE CONTAINS(companyname,'x<strong>SAP</strong> Corp Walldorf',<br />
FUZZY(0.7,'textSearch=compare,bestMatchingTokenWeight=0.7'))<br />
ORDER BY score DESC;<br />
SCORE ID COMPANYNAME<br />
0.94 2 <strong>SAP</strong> in Walldorf Corp<br />
Fuzzy Search on Two Columns<br />
1. Create the data.<br />
270<br />
CREATE COLUMN TABLE companies2<br />
(<br />
id INTEGER PRIMARY KEY,<br />
companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON,<br />
contact SHORTTEXT(100) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO companies2 VALUES (1, '<strong>SAP</strong> Corp', 'Mister Master');<br />
INSERT INTO companies2 VALUES (2, '<strong>SAP</strong> in Walldorf Corp', 'Master<br />
Mister');<br />
INSERT INTO companies2 VALUES (3, 'A<strong>SAP</strong>', 'Nister Naster');<br />
INSERT INTO companies2 VALUES (4, 'A<strong>SAP</strong> Corp', 'Mixter Maxter');<br />
INSERT INTO companies2 VALUES (5, 'B<strong>SAP</strong> orp', 'Imster Marter');<br />
INSERT INTO companies2 VALUES (6, 'IBM Corp', 'M. Master');<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
2. Perform the search on two columns.<br />
SELECT SCORE() AS score, * FROM companies2<br />
WHERE CONTAINS(companyname, 'IBM',<br />
FUZZY(0.7,'textSearch=compare,bestMatchingTokenWeight=0.7'))<br />
AND CONTAINS(contact, 'Master',<br />
FUZZY(0.7,'textSearch=compare,bestMatchingTokenWeight=0.7'))<br />
ORDER BY score DESC;<br />
SCORE ID COMPANYNAME CONTACT<br />
0.91 6 IBM Corp M. Master<br />
3. Perform a freestyle search.<br />
SELECT SCORE() AS score, * FROM companies2<br />
WHERE CONTAINS((companyname,contact), 'IBM Master', FUZZY(0.7))<br />
ORDER BY score DESC;<br />
SCORE ID COMPANYNAME CONTACT<br />
0.8 6 IBM Corp M. Master<br />
Note: <strong>Free</strong>style search always uses TF/IDF to calculate the score and does not support parameters<br />
such as 'textSearch=compare' or 'bestMatchingTokenWeight=0.7' that influence score calculation.<br />
Therefore, we get a different score for the same record.<br />
Fuzzy Search on String Columns<br />
String types support a basic fuzzy string search. The values of a column are compared with the user input using<br />
the fault-tolerant fuzzy string comparison.<br />
When working with string types, the fuzzy string compare always compares the full strings. When, for example,<br />
searching with '<strong>SAP</strong>', a record such as '<strong>SAP</strong> Deutschland AG & Co. KG' gets a very low score, because only a very<br />
small part of the string is equal (3 of 27 characters match).<br />
A fuzzy search on string types is a replacement for a non-fault-tolerant SQL statement such as<br />
SELECT ... FROM products WHERE product_name = 'coffe krisp biscuit' ...<br />
that would not return any results because of the spelling errors.<br />
Supported SQL data types are VARCHAR and NVARCHAR.<br />
It is possible to speed up the fuzzy search by creating additional data structures called 'fuzzy search indexes',<br />
which are used for a faster calculation of the fuzzy score. These indexes exist in the memory only, so no additional<br />
disk space is needed.<br />
To get the best response times possible, you should enable the fuzzy search indexes for all database columns that<br />
have a high load of fuzzy searches and for all database columns that are used in performance-critical queries.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 271
Use Case Fuzzy Search - House Numbers<br />
Score Calculation<br />
The house number comparison aims for a 'simple' solution that is easy to understand, gives good results, and<br />
works for most countries. The limitations of the algorithm are:<br />
● The algorithm focuses on numeric values - either a single number ('8') or a range of numbers ('8 - 12').<br />
● House number additions (for example, the 'a' in '8a') are either equal or not equal.<br />
When comparing two strings containing house numbers with each other, the score is calculated according to the<br />
rules described below.<br />
House number addition. A house number addition in terms of this backlog item is any additional text that is<br />
written before or after the numeric value of a house number.<br />
House number ranges. When a string contains at least two numbers and there is a dash between the first and<br />
second number, this is treated as a house number range. The first number is the lower bound of the range, the last<br />
number is the upper bound.<br />
Multiple numbers. When multiple numbers are part of a house number string that does not define a house<br />
number range, the first number is the house number used for the comparison. All remaining information is used<br />
as a house number addition.<br />
Whitespace characters. For all rules, whitespace characters are ignored when comparing the house numbers.<br />
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'.<br />
Symmetry. In all examples, the score calculation is symmetric. This means that either string 1 or string 2 can be<br />
the user input and the other string is stored in the database table.<br />
Rule 1 - House Numbers or House Number Ranges Are Identical<br />
For identical house numbers, a score of 1.0 is returned. Identical house numbers are house number strings that<br />
are equal when whitespace characters are ignored.<br />
Examples:<br />
String 1 String 2 Score<br />
5 5 1.0<br />
5a 5 a 1.0<br />
8-12 8-12 1.0<br />
9 in the backyard 9 in the backyard 0.9<br />
272<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Rule 2 - House Numbers or House Number Ranges Are Very Similar (House<br />
Number Additions Are Different)<br />
House numbers or house number ranges are considered very similar when the numeric values are identical but<br />
the additional information differs.<br />
Examples:<br />
String 1 String 2 Score<br />
5 5 a 0.9<br />
5a 5 b 0.9<br />
5 Nr. 5 0.9<br />
8-12 8 - 12a 0.9<br />
8-12 8 - 12/5 0.9<br />
8 this is a long text -12 8 - 12a 0.9<br />
7 below 7 0.9<br />
9 9 in the backyard 0.9<br />
9 in the backyard 9 in the backyard 0.9<br />
Rule 3 - House Numbers or House Number Ranges Are Less Similar<br />
House numbers and house number ranges are considered less similar in the following cases:<br />
1. A house number is compared to a house number range and the numeric value of the house number equals the<br />
lower or upper bound of the range.<br />
2. Two house number ranges are compared and the numeric value of either the lower or upper bound are equal.<br />
String 1 String 2 Score<br />
8 8-12 0.8<br />
12a 8-12 0.8<br />
8-10 8-12 0.8<br />
8-10 8-10/12 0.8<br />
10-12a 8-12 0.8<br />
8 in the backyard 8-12 0.8<br />
Rule 4 - Overlapping House Number Ranges<br />
House numbers and house number ranges overlap in the following cases:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 273
1. A house number is compared to a house number range and the numeric value of the house number lies within<br />
the range.<br />
2. Two house number ranges are compared and the ranges overlap.<br />
Examples:<br />
String 1 String 2 Score<br />
10 8-12 0.7<br />
10a 8-12 0.7<br />
9 8-12 0.7<br />
8-12 10-14 0.7<br />
8-12a 10b-14 0.7<br />
Last Rule - House Numbers Are Not Equal<br />
Examples:<br />
String 1 String 2 Score<br />
5 6 0.0<br />
8a 9a 0.0<br />
6 8-12 0.0<br />
8-10 12-14 0.0<br />
House Number Columns and Other String Search Options<br />
The following search options available for string column types are not valid for house number columns.<br />
SpellCheckFactor<br />
When comparing house numbers, the search option 'spellCheckFactor' is ignored. So for house numbers, the<br />
results are always the same as with 'spellCheckFactor=1.0'.<br />
SimilarCalculationMode<br />
When comparing house numbers, the search option 'similarCalculationMode' is ignored and has no effect on the<br />
search result. Both options are ignored, no error is returned when any of the options is given.<br />
SQL Syntax<br />
To enable the search for house numbers on an (N)VARCHAR column, the FUZZY SEARCH MODE clause is used in<br />
a CREATE TABLE statement.<br />
CREATE COLUMN TABLE tab<br />
(<br />
id INTEGER PRIMARY KEY,<br />
274<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
col1 NVARCHAR(20) FUZZY SEARCH MODE 'housenumber'<br />
);<br />
To enable or disable the house number search mode at a later point in time, you use the ALTER TABLE statement.<br />
The fuzzy search mode is not changed if the FUZZY SEARCH MODE clause is omitted.<br />
-- enable housenumber search<br />
ALTER TABLE tab ALTER<br />
(<br />
col1 VARCHAR(20) FUZZY SEARCH MODE 'housenumber'<br />
);<br />
-- disable housenumber search<br />
ALTER TABLE tab ALTER<br />
(<br />
col1 VARCHAR(20) FUZZY SEARCH MODE NULL<br />
);<br />
-- do not change the status of the search mode<br />
ALTER TABLE tab ALTER<br />
(<br />
col1 VARCHAR(20)<br />
);<br />
You can query the state of the fuzzy search mode by using the system view TABLE_COLUMNS.<br />
SELECT column_name, data_type_name, fuzzy_search_mode<br />
FROM table_columns<br />
WHERE table_name = 'TAB';<br />
Example<br />
Note: You cannot use a fuzzy search index in combination with the house number search mode.<br />
The following example creates a table that contains a single house number column only and executes some<br />
searches on this column.<br />
CREATE COLUMN TABLE housenumbers<br />
(<br />
housenumber NVARCHAR(50) FUZZY SEARCH MODE 'housenumber'<br />
);<br />
INSERT INTO housenumbers VALUES ('5');<br />
INSERT INTO housenumbers VALUES ('5a');<br />
INSERT INTO housenumbers VALUES ('5 a');<br />
INSERT INTO housenumbers VALUES ('Nr. 5');<br />
INSERT INTO housenumbers VALUES ('8-12');<br />
INSERT INTO housenumbers VALUES ('8 - 12');<br />
INSERT INTO housenumbers VALUES ('8 - 12a');<br />
INSERT INTO housenumbers VALUES ('Nr. 8-12');<br />
INSERT INTO housenumbers VALUES ('8 - 12/5');<br />
INSERT INTO housenumbers VALUES ('8');<br />
INSERT INTO housenumbers VALUES ('12a');<br />
INSERT INTO housenumbers VALUES ('8-10');<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 275
INSERT INTO housenumbers VALUES ('10-12a');<br />
INSERT INTO housenumbers VALUES ('10a');<br />
INSERT INTO housenumbers VALUES ('10-14');<br />
INSERT INTO housenumbers VALUES ('9');<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM housenumbers<br />
WHERE CONTAINS(housenumber, '5', FUZZY(0.8))<br />
ORDER BY TO_DECIMAL(SCORE(),3,2) DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM housenumbers<br />
WHERE CONTAINS(housenumber, 'Nr. 5', FUZZY(0.8))<br />
ORDER BY TO_DECIMAL(SCORE(),3,2) DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM housenumbers<br />
WHERE CONTAINS(housenumber, '8a-12', FUZZY(0.8))<br />
ORDER BY TO_DECIMAL(SCORE(),3,2) DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM housenumbers<br />
WHERE CONTAINS(housenumber, '10-12', FUZZY(0.8))<br />
ORDER BY TO_DECIMAL(SCORE(),3,2) DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM housenumbers<br />
WHERE CONTAINS(housenumber, '9 in the BACKYARD', FUZZY(0.8))<br />
ORDER BY TO_DECIMAL(SCORE(),3,2) DESC;<br />
Use Case Fuzzy Search - Postcodes<br />
Postcodes in almost all countries are ordered by region. This means that if the leading characters of the<br />
postcodes of two different addresses are the same, the addresses are near to each other. In Germany, for<br />
example, addresses within large cities share the first or even the first two digits of their postcode.<br />
The only exception known to the development team is Cambodia, where postcodes are not ordered by region.<br />
When doing a fuzzy search on addresses, it makes sense to return a higher score for postcodes that are 'near' to a<br />
given user input than for postcodes that are 'far away' from the user input. It makes sense to give a higher weight<br />
to the leading characters and a lower weight to the trailing characters of the postcode.<br />
Valid addresses may contain a country code in front of the postcode (for example, 'D-12345' or 'DE-12345' for a<br />
German address). This is also supported by the fuzzy postcode search.<br />
Score Calculation<br />
Before the fuzzy score is calculated, the postcode strings are standardized.<br />
1. Country codes are separated from the postcode strings. Country codes in this case consist of one to three<br />
276<br />
letters (a-z only, no numbers) at the beginning of the postcode, followed by a minus sign. Longer words are<br />
not considered a country code because postal standards do not allow country names in front of the postcode.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
2. Country codes are standardized to enable a comparison of different codes for the same country, for example,<br />
'D-', 'DE-' and 'DEU-' for German postcodes. All unknown/invalid country codes are standardized to one<br />
special 'dummy' country code.<br />
3. Spaces and dashes are removed from the remaining postcode.<br />
4. All letters are standardized to uppercase.<br />
User Input Country Code Remaining Postcode<br />
71691 71691<br />
716 91 71691<br />
D-71691 D 71691<br />
DE-71 691 DE 71691<br />
D 71691 D71691<br />
Germany-71691 GERMANY71691<br />
GB-A1H 2ZU GB A1H2ZU<br />
A1H-2ZU A1H2ZU<br />
gb-A1h 2zu GB A1H2ZU<br />
XY-12345 XX 12345<br />
zz-12345 XX 12345<br />
AI-2640 AI 2640<br />
The last example is the only known example where the country code is part of the postcode (AI = Anguilla). The<br />
algorithm works here as well, as the country code is also compared. The two examples directly above the AI<br />
example show invalid country codes. Both are standardized to the same non-existent 'dummy' country code.<br />
Postcode Comparison<br />
The standardized postcodes are compared using a variation of the fuzzy string comparison. This variation gives a<br />
higher weight to the first two characters of the postcode.<br />
Country codes are given the same weight as a single character at the end of the postcode.<br />
● Only postcodes with the same country code can get a score of 1.0.<br />
● If one country code is given and the second country code is empty, the score of the postcode comparison is<br />
less than 1.0.<br />
● If both country codes are given and are different, the score of the postcode comparison is also less than 1.0.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 277
Parameter similarCalculationMode<br />
The search option 'similarCalculationMode' with options 'search' and 'symmetricsearch' is available for postcode<br />
columns.<br />
When using the search option 'similarCalculationMode', a postcode search with a postcode prefix will find all<br />
addresses in a given area.<br />
● A search with '71' returns all postcodes beginning with '71'.<br />
● A search with '1234' returns all postcodes starting with a sequence similar to '1234' and, with a lower score, all<br />
postcodes that contain a '1234'.<br />
Parameter spellCheckFactor<br />
Two postcodes may be considered identical by the fuzzy string comparison, but may still be different. In this case,<br />
the value of the parameter 'spellCheckFactor' is applied and the score is multiplied by the spellCheckFactor.<br />
Examples for non-equal postcodes that get a score of 1.0 are:<br />
● '123456' and '12 34 56'<br />
● '7070717' and '7071707'<br />
The default value of the search option spellCheckFactor is 0.9. To disable this feature, set 'spellCheckFactor=1.0'.<br />
Example<br />
The following example uses a spellCheckFactor of 1.0, which is not the default value.<br />
Postcode 1 Postcode 2 Score Remarks<br />
71691 71691 1.0<br />
71691 71 691 1.0<br />
71691 81691 0.51 Highest weight on the<br />
first digit<br />
71691 72691 0.7 High weight on the<br />
second digit<br />
71691 71692 0.96 Lower weight on all<br />
other digits<br />
71691 D-71691 0.96 Country code missing<br />
in one column<br />
D-71691 A-71691 0.96 Country codes are<br />
71691 D-71692 0.92<br />
D-71691 A-71692 0.92<br />
278<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
different<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Postcode 1 Postcode 2 Score Remarks<br />
GB-A1H 2ZU Gb-a1h2zu 1.0<br />
XX-12345 YY-12345 1.0 Invalid country codes<br />
are 'equal'<br />
D-12345 YY-12345 0.96 Valid and invalid<br />
SQL Syntax<br />
country code<br />
(N)VARCHAR columns have to be defined as postcode columns to enable the fuzzy postcode search. You do this<br />
by using the FUZZY SEARCH MODE clause.<br />
In addition, it is also possible to increase the performance of the postcode search by activating a fuzzy search<br />
index and by creating a database index on the postcode column.<br />
CREATE COLUMN TABLE tab<br />
(<br />
id INTEGER PRIMARY KEY,<br />
postcode NVARCHAR(20) FUZZY SEARCH INDEX ON FUZZY SEARCH MODE<br />
'postcode'<br />
);<br />
CREATE INDEX myindex1 ON tab(postcode);<br />
The postcode search can be enabled or disabled at a later point in time with the ALTER TABLE statement. Do not<br />
specify the FUZZY SEARCH MODE clause to disable the postcode search.<br />
-- enable postcode search<br />
ALTER TABLE tab ALTER<br />
(<br />
postcode NVARCHAR(100) FUZZY SEARCH MODE 'postcode'<br />
);<br />
-- disable postcode search<br />
ALTER TABLE tab ALTER<br />
(<br />
postcode NVARCHAR(100) FUZZY SEARCH MODE NULL<br />
);<br />
-- do not change the status of the search mode<br />
ALTER TABLE tab ALTER<br />
(<br />
postcode NVARCHAR(100)<br />
);<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 279
You can query the status of the fuzzy search index and the fuzzy search mode from the system view<br />
TABLE_COLUMNS.<br />
SELECT column_name, data_type_name, fuzzy_search_index, fuzzy_search_mode<br />
FROM table_columns<br />
WHERE table_name = 'TAB';<br />
Example<br />
CREATE COLUMN TABLE postcodes<br />
(<br />
postcode NVARCHAR(50) FUZZY SEARCH INDEX ON FUZZY SEARCH MODE 'postcode'<br />
);<br />
INSERT INTO postcodes VALUES ('71691');<br />
INSERT INTO postcodes VALUES ('81691');<br />
INSERT INTO postcodes VALUES ('72691');<br />
INSERT INTO postcodes VALUES ('71692');<br />
INSERT INTO postcodes VALUES ('716 91');<br />
INSERT INTO postcodes VALUES ('A1H 2ZU');<br />
INSERT INTO postcodes VALUES ('A1H2ZU');<br />
INSERT INTO postcodes VALUES ('D-71691');<br />
INSERT INTO postcodes VALUES ('D-71692');<br />
INSERT INTO postcodes VALUES ('A-71691');<br />
INSERT INTO postcodes VALUES ('A-71692');<br />
INSERT INTO postcodes VALUES ('DE-71 691');<br />
INSERT INTO postcodes VALUES ('D 71691');<br />
INSERT INTO postcodes VALUES ('GB-A1H 2ZU');<br />
INSERT INTO postcodes VALUES ('XX-12345');<br />
INSERT INTO postcodes VALUES ('D-12345');<br />
INSERT INTO postcodes VALUES ('71234');<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM postcodes<br />
WHERE CONTAINS(postcode, '71691', FUZZY(0.5, 'spellCheckFactor=1.0'))<br />
ORDER BY SCORE() DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM postcodes<br />
WHERE CONTAINS(postcode, 'D-71691', FUZZY(0.5, 'spellCheckFactor=1.0'))<br />
ORDER BY SCORE() DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM postcodes<br />
WHERE CONTAINS(postcode, 'Gb-a1h2zu', FUZZY(0.5, 'spellCheckFactor=1.0'))<br />
ORDER BY SCORE() DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM postcodes<br />
WHERE CONTAINS(postcode, 'YY-12345', FUZZY(0.5, 'spellCheckFactor=1.0'))<br />
ORDER BY SCORE() DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *FROM postcodes<br />
WHERE CONTAINS(postcode, '71', FUZZY(0.5, 'spellCheckFactor=1.0'))<br />
ORDER BY SCORE() DESC;<br />
SELECT TO_DECIMAL(SCORE(),3,2), *<br />
FROM postcodes<br />
280<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
WHERE CONTAINS(postcode, '1234', FUZZY(0.5, 'spellCheckFactor=1.0'))<br />
ORDER BY SCORE() DESC;<br />
Fuzzy Search on Text Columns<br />
Text types support a more sophisticated kind of fuzzy search. Texts are tokenized (split into terms) and the fuzzy<br />
comparison is done term by term. For example, when searching with '<strong>SAP</strong>', a record such as '<strong>SAP</strong> Deutschland AG<br />
& Co. KG' gets a high score, because the term '<strong>SAP</strong>' exists in both texts. A record such as '<strong>SAP</strong>PHIRE NOW<br />
Orlando' gets a lower score, because '<strong>SAP</strong>' is only a part of the longer term '<strong>SAP</strong>PHIRE' (3 of 8 characters match).<br />
Fuzzy search on text columns replaces non-fault-tolerant statements such as<br />
SELECT ... FROM documents WHERE doc_content LIKE '% Driethanolamyn %' ...<br />
The following SQL data types are supported:<br />
● TEXT<br />
● SHORTTEXT<br />
● fulltext index<br />
A fulltext index is an additional index structure that can be defined for non-text columns to add text search<br />
features. Supported column types are, for example, NCLOB and NVARCHAR.<br />
It is possible to speed up the fuzzy search by creating data structures called 'fuzzy search indexes', which are<br />
used for a faster calculation of the fuzzy score. These indexes exist in the memory only, so no additional disk<br />
space is needed.<br />
To get the best response times possible, you should enable the fuzzy search indexes for all database columns that<br />
have a high load of fuzzy searches and for all database columns that are used in performance-critical queries.<br />
Fuzzy Search on SQL Type TEXT<br />
A call to contains that references a TEXT column is automatically processed as a text search. In this case, the<br />
mode textsearch=compare and all fuzzy search options are allowed:<br />
CREATE COLUMN TABLE mytable<br />
(<br />
col1 TEXT<br />
);<br />
SELECT score() AS score, * FROM mytable WHERE contains(col1, 'a b',<br />
fuzzy(0.8, 'textsearch=compare'));<br />
Fuzzy Search on SQL Type SHORTTEXT<br />
When a SHORTTEXT column is created, a column of column store type cs_string and a second hidden text<br />
column are created. A call to contains that references the SHORTTEXT column is automatically redirected by the<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 281
freestyler to the additional hidden TEXT column. In this case, the mode textsearch=compare and all fuzzy search<br />
options are allowed:<br />
CREATE COLUMN TABLE mytable<br />
(<br />
col1 SHORTTEXT(200)<br />
);<br />
SELECT score() AS score, * FROM mytable WHERE contains(col1, 'a b',<br />
fuzzy(0.8, 'textsearch=compare'));<br />
Fuzzy Search on a FULLTEXT INDEX<br />
When a full text index is created on a column that is not of type TEXT (e.g. NVARCHAR, NCLOB, ...) a hidden text<br />
column is added to the table. A call to contains that references the non-TEXT column is automatically redirected<br />
by the freestyler to the additional text column. In this case, the mode textsearch=compare and all fuzzy search<br />
options are allowed:<br />
CREATE COLUMN TABLE mytable<br />
(<br />
col1 NVARCHAR(2000)<br />
);<br />
CREATE FULLTEXT INDEX myindex ON mytable(col1);<br />
SELECT score() AS score, * FROM mytable WHERE contains(col1, 'a b',<br />
fuzzy(0.8, 'textsearch=compare'));<br />
Merge Delta for Better Performance<br />
When inserting or loading a large number of rows in a table that has a TEXT or SHORTTEXT column or that uses a<br />
FULLTEXT INDEX, it is important to merge the delta part of the table to get a good search performance.<br />
A delta merge can be started manually with the following SQL statement:<br />
MERGE DELTA OF mytable;<br />
Alternatively, a delta merge can be triggered automatically by the mergedog process.<br />
Fuzzy Multi-Token Search on Text Columns<br />
Content Types<br />
When using more than one token within a query, the default content type is AND (for example, ... WHERE<br />
CONTAINS (mycolumn, 'software firm', FUZZY(0.5)) ... will return entries that contain a token similar to 'software'<br />
and a token similar to 'firm').<br />
Alternatively, you can use OR by adding the key word between the tokens (for example, ... WHERE CONTAINS<br />
(mycolumn, 'apple OR 'banana', FUZZY(0.5)) ... will return entries that contain a token similar to 'apple' and<br />
entries that contain a token similar to 'banana').<br />
282<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
PHRASE is similar to AND but restricts hits to those that contain the tokens as a phrase, that is, in the same order<br />
and with nothing between them. A PHRASE is indicated by adding double quotes around the tokens, within the<br />
single quotes (for example, ... WHERE CONTAINS (mycolumn, '"day dream"', FUZZY(0.5)) ... will not return an<br />
entry containing 'I dream of a day').<br />
The content type AND that is used for a full-text search (default behavior: textSearch=fulltext) is implemented as<br />
a logical AND to achieve better performance. For example, a search for 'Miller & Miller AG' with content type AND<br />
matches 'Miller AG'.<br />
textSearch=compare should be used for duplicate detection and for comparing company names, product names,<br />
and so on. Here, search results are better because of the strict AND comparison that is used. In other words, if<br />
you search for 'Miller & Miller' with content type AND, only records that contain the term 'Miller' at least twice are<br />
returned.<br />
A strict AND assigns terms from the user input to terms in the database entry only once (and vice versa). For<br />
more information, see Fuzzy Multi-Token Search with Soft AND [page 285].<br />
Parameters Influencing the Score<br />
Name of Option Range Default Applies to Types<br />
bestMatchingTokenWeigh<br />
t<br />
considerNonMatchingTok<br />
ens<br />
Formula for score calculation:<br />
0.0..1.0 not set TEXT<br />
max, min, all, input, table max TEXT<br />
score = bestMatchingTokenWeight x max(tokenScores) + (1-bestMatchingTokenWeight) x √(Σ(tokenScore²)/<br />
tokenCount)<br />
tokenCount is determined according to the parameter considerNonMatchingTokens as follows:<br />
● input: Use search term token count<br />
● table: Use column value token count<br />
● all: Use sum of search and column value token count (where the numerator is multiplied by 2)<br />
● min: Use smaller value of token counts<br />
● max: Use larger value of token counts (default)<br />
Recommendations for specific search content types<br />
If you are using an "OR" search (searching for "this or that"), you should set considerNonMatchingTokens to table<br />
to get a useful score assessment.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 283
Example<br />
DROP TABLE test_table;<br />
CREATE COLUMN TABLE test_table<br />
(<br />
id INTEGER PRIMARY KEY,<br />
t SHORTTEXT(200) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO test_table VALUES ('1','eins');<br />
INSERT INTO test_table VALUES ('2','eins zwei');<br />
INSERT INTO test_table VALUES ('3','eins zwei drei');<br />
INSERT INTO test_table VALUES ('4','eins zwei drei vier');<br />
INSERT INTO test_table VALUES ('5','eins zwei drei vier funf');<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table<br />
WHERE CONTAINS(t, 'eins zwoi drei',<br />
FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=1.0'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
1 3 eins zwei drei<br />
1 4 eins zwei drei vier<br />
1 5 eins zwei drei vier funf<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table<br />
WHERE CONTAINS(t, 'eins zwoi drei',<br />
FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=0'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
0.92 3 eins zwei drei<br />
0.8 4 eins zwei drei vier<br />
0.71 5 eins zwei drei vier funf<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table<br />
WHERE CONTAINS(t, 'eins zwoi drei',<br />
FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=0,considerNonMatching<br />
Tokens=all'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
0.92 3 eins zwei drei<br />
0.85 4 eins zwei drei vier<br />
0.8 5 eins zwei drei vier funf<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test_table<br />
WHERE CONTAINS(t, 'eins zwoi drei',<br />
FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=0,considerNonMatching<br />
284<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Tokens=input'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
0.92 3 eins zwei drei<br />
0.92 4 eins zwei drei vier<br />
0.92 5 eins zwei drei vier funf<br />
Parameters Influencing the Result Set<br />
Option Range Default Applies to Types<br />
andSymmetric on,off off TEXT<br />
andThreshold 0.0..1.0 1.0 TEXT<br />
For examples, see Fuzzy Multi-Token Search with Soft AND [page 285] .<br />
Fuzzy Multi-Token Search with Soft AND<br />
A fuzzy search on one text column can also use a softer AND, so that not all tokens used in the search term have<br />
to match the result.<br />
There are two parameters that control this behavior:<br />
Option Name Range Default Applies to Types Short Description<br />
andSymmetric on,off off TEXT Activates a<br />
symmetric AND<br />
content search<br />
andThreshold 0.0..1.0 1.0 TEXT Determines the<br />
Creating example data:<br />
DROP TABLE test_soft_and;<br />
CREATE COLUMN TABLE test_soft_and<br />
(<br />
id INTEGER PRIMARY KEY,<br />
t SHORTTEXT(200) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO test_soft_and VALUES ('1','eins');<br />
INSERT INTO test_soft_and VALUES ('2','eins zwei');<br />
INSERT INTO test_soft_and VALUES ('3','eins zwei drei');<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
percentage of<br />
tokens that need to<br />
match<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 285
INSERT INTO test_soft_and VALUES ('4','eins zwei drei vier');<br />
INSERT INTO test_soft_and VALUES ('5','eins zwei drei vier funf');<br />
Search with andSymmetric=off<br />
SELECT SCORE() AS score, * FROM test_soft_and<br />
WHERE CONTAINS(T, 'eins zwei drei', FUZZY(0.5,<br />
'andSymmetric=off,bestMatchingTokenWeight=0.5,textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
1 3 eins zwei drei<br />
0.933012723922729 4 eins zwei drei vier<br />
0.887298345565796 5 eins zwei drei vier funf<br />
Search with andSymmetric=on<br />
SELECT SCORE() AS score, * FROM test_soft_and<br />
WHERE CONTAINS(T, 'eins zwei drei',<br />
FUZZY(0.5,'andSymmetric=on,bestMatchingTokenWeight=0.5,textSearch=compare')<br />
)<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
1 3 eins zwei drei<br />
0.933012723922729 4 eins zwei drei vier<br />
0.90824830532074 2 eins zwei<br />
0.887298345565796 5 eins zwei drei vier funf<br />
0.788675129413605 1 eins<br />
Search with andThreshold<br />
SELECT SCORE() AS score, * FROM test_soft_and<br />
WHERE CONTAINS(T, 'eins XXX drei vier',<br />
FUZZY(0.5,'andThreshold=0.75,bestMatchingTokenWeight=0.5,textSearch=compare<br />
'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
0.933012723922729 4 eins zwei drei vier<br />
0.887298345565796 5 eins zwei drei vier funf<br />
SELECT SCORE() AS score, * FROM test_soft_and<br />
WHERE CONTAINS(T, 'eins XXX drei vier',<br />
FUZZY(0.5,'andThreshold=0.5,bestMatchingTokenWeight=0.5,textSearch=compare'<br />
286<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
))<br />
ORDER BY score DESC, id;<br />
SCORE ID T<br />
0.933012723922729 4 eins zwei drei vier<br />
0.887298345565796 5 eins zwei drei vier funf<br />
0.853553414344788 3 eins zwei drei<br />
Option abbreviationSimilarity<br />
The option abbreviationSimilarity is used to search for and find a word using its first character and vice versa with<br />
a given score. With abbreviationSimilarity = 0.9, a SELECT retrieves “word” with SCORE = 0.9 when you search<br />
with “w” (and vice versa).<br />
CREATE COLUMN TABLE abbrev<br />
(<br />
id INTEGER PRIMARY KEY,<br />
name SHORTTEXT(200) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO abbrev VALUES ('1','Peter');<br />
INSERT INTO abbrev VALUES ('2','Hans');<br />
INSERT INTO abbrev VALUES ('3','H.');<br />
INSERT INTO abbrev VALUES ('4','P.');<br />
INSERT INTO abbrev VALUES ('5','Hans-Peter');<br />
INSERT INTO abbrev VALUES ('6','H.-P.');<br />
INSERT INTO abbrev VALUES ('7','HP');<br />
INSERT INTO abbrev VALUES ('8','G Gerd');<br />
INSERT INTO abbrev VALUES ('9','G');<br />
INSERT INTO abbrev VALUES ('10','Gerd');<br />
Search one token with abbreviationSimilarity<br />
SELECT SCORE() AS score, id, name FROM abbrev<br />
WHERE CONTAINS(name, 'HP', FUZZY(0.5,<br />
'abbreviationSimilarity=0.80,textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID NAME<br />
1 7 HP<br />
0.800000011920929 3 H.<br />
0.565685451030731 6 H.-P.<br />
Search two tokens with abbreviationSimilarity<br />
SELECT SCORE() AS score, id, name FROM abbrev<br />
WHERE CONTAINS(name, 'Hans Peter',FUZZY(0.5,<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 287
'abbreviationSimilarity=0.80,textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID NAME<br />
1 5 Hans-Peter<br />
0.800000011920929 6 H.-P.<br />
Search two tokens with abbreviationSimilarity<br />
SELECT SCORE() AS score, id, name FROM abbrev<br />
WHERE CONTAINS(name, 'Go Gerd',FUZZY(0.5,<br />
'abbreviationSimilarity=0.80,textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID NAME<br />
0.905538558959961 8 G Gerd<br />
Option minTextScore<br />
The minTextScore option allows you to set the score a text field has to reach to be a match.<br />
Note: If you use a fuzzySimilarity of 0.0, the parameter minTextScore will be redundant.<br />
DROP TABLE tab_mintextscore;<br />
CREATE COLUMN TABLE tab_mintextscore<br />
(<br />
id INTEGER PRIMARY KEY,<br />
t TEXT FAST PREPROCESS ON FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO tab_mintextscore VALUES ('1','Bert');<br />
INSERT INTO tab_mintextscore VALUES ('2','Berta');<br />
INSERT INTO tab_mintextscore VALUES ('3','Bart');<br />
Search on a text column<br />
SELECT SCORE() AS score, id, t FROM tab_mintextscore<br />
WHERE CONTAINS(t, 'Ernie OR Bert', FUZZY(0.100, 'textSearch=compare,<br />
bestMatchingTokenWeight=0,minTextScore=0.70'))<br />
ORDER BY score DESC, id;<br />
SCORE ID T Description<br />
0.7 1 Bert
Option textSearch<br />
The textSearch option is used to select the search algorithm for TEXT columns:<br />
● textSearch=fulltext (default value): A full-text search is done on a TEXT column. IDF calculation or<br />
specialOrRanking (depending on search flags) is used. This is the 'old' NewDB behavior.<br />
● textSearch=compare: A search similar to a Fuzzy Double search is done. Additional search options are<br />
enabled.<br />
Allowed search options and error handling<br />
Depending on the data type of a column and the type of the search (freestyle or attribute search) of a query entry,<br />
some of the searchOptions parameters are not allowed because they do not make sense.<br />
If the user sets an option that is not allowed, a SQL error is thrown and the SELECT aborts.<br />
textSearch=compar<br />
e<br />
FUZZY-Double-like<br />
search on TEXT<br />
attribute search and<br />
textSearch=<br />
compare and<br />
datatype= TEXT<br />
Full-text search on<br />
TEXT<br />
attribute search and<br />
textSearch= fulltext<br />
and datatype= TEXT<br />
<strong>Free</strong>style full-text<br />
search<br />
freestyle search and<br />
textSearch= fulltext<br />
YES n/a n/a NO<br />
textSearch=fulltext n/a YES n/a (default mode) NO<br />
similarCalculationM<br />
ode<br />
YES YES YES YES<br />
spellCheckFactor YES YES YES YES<br />
fuzzySimilarity > 0 YES YES YES YES<br />
fuzzySimilarity = 0 YES NO NO YES<br />
Search on types<br />
other than TEXT<br />
attribute search and<br />
datatype TEXT<br />
emptyScore YES NO NO YES (Only valid for<br />
abbreviationSimilarit<br />
y<br />
YES NO NO NO<br />
text, string and date<br />
types. Numeric<br />
types are not<br />
supported.)<br />
maxDateDistance NO NO YES YES (Only valid for<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
date types. Other<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 289
termMappingTable/<br />
ListId<br />
stopwordTable/<br />
ListId<br />
FUZZY-Double-like<br />
search on TEXT<br />
Full-text search on<br />
TEXT<br />
<strong>Free</strong>style full-text<br />
search<br />
YES YES YES NO<br />
YES NO NO NO<br />
andThreshold YES NO NO NO<br />
andSymmetric YES NO NO NO<br />
bestMatchingToken<br />
Weight<br />
considerNonMatchin<br />
gTokens<br />
YES NO NO NO<br />
YES NO NO NO<br />
minTextScore YES NO NO NO<br />
Rank Calculation fuzzy score IDF IDF (TEXT) or fuzzy<br />
Legend<br />
YES - The parameter is allowed.<br />
score (other types)<br />
NO - The parameter is not allowed and an error message is returned if the user sets this option.<br />
Search on types<br />
other than TEXT<br />
types are not<br />
supported.)<br />
fuzzy score<br />
ignored - The parameter is ignored and no error message is returned to the user. This is necessary because the<br />
freestyler passes all search options to the generated search on single columns.<br />
Rank calculation<br />
When 'fulltext' is specified, the search is done using IDF or specialOrRanking (depending on the search flags). The<br />
fuzzy score is not calculated.<br />
When 'compare' is specified, the fuzzy score is calculated using bestMatchingTokenWeight and<br />
considerNonMatchingTokens. The user does not have to set these options. In this case, the default values are<br />
used.<br />
290<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Fuzzy Search with Stopwords<br />
Usage<br />
Stopwords are terms that are less significant for a search and are therefore not used to generate the result set. In<br />
other words, the search is carried out as if the stopwords are not present (either in the user input or in the<br />
database column).<br />
However, stopwords influence the score that is calculated. A record with stopwords identical to the user input<br />
gets a higher score than a record with differing or missing stopwords.<br />
Stopwords can be defined either as single terms or as stopword phrases consisting of multiple terms. Stopword<br />
phrases are only applied when all terms of the stopword appear in exactly the given order.<br />
Use case example: When searching for company names, the legal form (Ltd, SA, AG, and so on) is less significant<br />
and less selective than the other parts of the name.<br />
Stopwords are stored in a column-store table with the following format:<br />
CREATE COLUMN TABLE mystopwords<br />
(<br />
stopword_id VARCHAR(32) PRIMARY KEY,<br />
list_id VARCHAR(32) NOT NULL,<br />
language_code CHAR(2),<br />
term NVARCHAR(200) NOT NULL<br />
);<br />
Stopwords are language dependent. It is possible to define the language that a stopword is valid for. You can also<br />
define stopwords for all languages by not setting a language.<br />
(It makes sense to add the language information now so that you can make use of the feature when it is available,<br />
without having to change the stopword definitions.)<br />
As with term mappings, stopwords can be grouped together in multiple groups. Groups of stopwords are<br />
identified by the value of the list_id column that is part of the stopword table.<br />
INSERT INTO mystopwords VALUES (1, 'legalform', '', 'Ltd');<br />
INSERT INTO mystopwords VALUES (2, 'legalform', 'de', 'GmbH');<br />
INSERT INTO mystopwords VALUES (3, 'legalform', 'de', 'Gesellschaft mit<br />
beschränkter Haftung');<br />
INSERT INTO mystopwords VALUES (4, 'legalform', 'de', 'AG');<br />
INSERT INTO mystopwords VALUES (5, 'legalform', 'de',<br />
'Aktiengesellschaft');<br />
To activate stopwords for a search on a TEXT column, you need to provide two search options (similar to the<br />
options used for term mappings):<br />
● stopwordListId=mylist1,mylist2,mylist3<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 291
● stopwordTable=[.]<br />
SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata<br />
WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare,<br />
stopwordTable=MYSTOPWORDS, stopwordListId=legalform'))<br />
ORDER BY score DESC;<br />
To activate language-specific stopwords, you must provide the language parameter:<br />
SELECT TO_DECIMAL(SCORE(),3,2) as score, company FROM mydata<br />
WHERE CONTAINS(company, 'xy gmbh', FUZZY(0.7, 'textsearch=compare,<br />
stopwordTable=MYSTOPWORDS, stopwordListId=legalform'), language('de'))<br />
ORDER BY score DESC;<br />
Note: In this case, all stopwords where language_code is set to 'de' or empty will be used. Any stopwords<br />
with other language codes will be ignored.<br />
Stopwords are removed from the search term first. In this example, the result set of the search is the same as for<br />
the search '... WHERE CONTAINS(company, 'xy', ...'.<br />
When calculating the score, the fuzzy scores of the non-stopword terms have the biggest influence on the<br />
resulting score. Stopwords in the user input and in the database records are also given less weight than the non-<br />
stopword terms, so records with matching stopwords get a higher score than records with differing or missing<br />
stopwords.<br />
The result of the above example is as follows:<br />
Score Company Comment<br />
1.00 XY GmbH<br />
0.95 XY Missing stopword<br />
0.95 XY Aktiengesellschaft Differing stopword<br />
0.92 XY Gesellschaft mit beschränkter<br />
Haftung<br />
Many differing stopwords<br />
0.78 XY Company Additional non-matching term, no<br />
stopword<br />
The value given for stopwordTable can be any valid SQL identifier as defined in the SQL reference manual. If<br />
schema is omitted, the current schema is used. The following examples all reference the same stopword table.<br />
SET SCHEMA schema1;<br />
SELECT ... WHERE CONTAINS(c, 'xy', FUZZY(0.7,<br />
'stopwordTable=schema1.mystopwords, ...'))...;<br />
SELECT ... WHERE CONTAINS(c, 'xy', FUZZY(0.7,<br />
'stopwordTable="SCHEMA1"."MYSTOPWORDS", ...'))...;<br />
SELECT ... WHERE CONTAINS(c, 'xy', FUZZY(0.7,<br />
'stopwordTable=mystopwords, ...'))...;<br />
292<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Stopword Example<br />
CREATE COLUMN TABLE stopwords<br />
(<br />
stopword_id VARCHAR(32) PRIMARY KEY,<br />
list_id VARCHAR(32) NOT NULL,<br />
language_code CHAR(2) NOT NULL,<br />
term NVARCHAR(200) NOT NULL<br />
);<br />
CREATE COLUMN TABLE companies<br />
(<br />
id INTEGER PRIMARY KEY,<br />
companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO companies VALUES ('1', '<strong>SAP</strong> AG');<br />
INSERT INTO companies VALUES ('2', '<strong>SAP</strong> Aktiengesellschaft');<br />
INSERT INTO stopwords VALUES ('1', '01', 'de', 'AG');<br />
INSERT INTO stopwords VALUES ('2', '01', 'de', 'Aktiengesellschaft');<br />
INSERT INTO stopwords VALUES ('3', '01', 'de', 'blub');<br />
Query 1: User input without stopwords. Stopwords in the database table only.<br />
SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, *<br />
FROM companies<br />
WHERE CONTAINS(companyname, 'sap', FUZZY(0.8, 'stopwordTable=stopwords,<br />
stopwordListId=01, textSearch=compare'))<br />
ORDER BY score DESC, ID;<br />
SCORE ID COMPANYNAME<br />
0.95 1 <strong>SAP</strong> AG<br />
0.95 2 <strong>SAP</strong> Aktiengesellschaft<br />
Query 2: User input with stopword. Other stopwords in the database table.<br />
SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, *<br />
FROM companies<br />
WHERE CONTAINS (companyname, 'sap blub', FUZZY(0.8,<br />
'stopwordTable=stopwords, stopwordListId=01, textSearch=compare'))<br />
ORDER BY score DESC, ID;<br />
SCORE ID COMPANYNAME<br />
0.95 1 <strong>SAP</strong> AG<br />
0.95 2 <strong>SAP</strong> Aktiengesellschaft<br />
Query 3: User input with stopword. One record with matching stopword, one record with differing stopword.<br />
SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, *<br />
FROM companies<br />
WHERE CONTAINS (companyname, 'sap aktiengesellschaft', FUZZY(0.8,<br />
'stopwordTable=stopwords, stopwordListId=01, textSearch=compare'))<br />
ORDER BY score DESC, ID;<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 293
SCORE ID COMPANYNAME<br />
1 2 <strong>SAP</strong> Aktiengesellschaft<br />
0.95 1 <strong>SAP</strong> AG<br />
Query 4: User input with two stopwords. Database records with one matching stopword.<br />
SELECT TO_DECIMAL(SCORE(), 3, 2) AS score, *<br />
FROM companies<br />
WHERE CONTAINS (companyname, 'sap ag aktiengesellschaft', FUZZY(0.8,<br />
'stopwordTable=stopwords, stopwordListId=01, textSearch=compare'))<br />
ORDER BY score DESC, ID;<br />
SCORE ID COMPANYNAME<br />
0.97 1 <strong>SAP</strong> AG<br />
0.97 2 <strong>SAP</strong> Aktiengesellschaft<br />
Stopwords Combined With Term Mappings<br />
When stopwords and term mappings are combined in a single query, term mappings are applied first. Stopwords<br />
are then applied to all variations of the search term created by the term mappings.<br />
Example<br />
Let us assume that you have defined the following term mapping:<br />
Term 1 Term 2<br />
Incredible Busy Machines IBM<br />
Ltd Limited<br />
Now you search for "Incredible Busy Machines Ltd".<br />
The search would be carried out for all possible search terms:<br />
Search Terms<br />
Incredible Busy Machines Ltd<br />
Incredible Busy Machines Limited<br />
IBM Ltd<br />
IBM Limited<br />
Let us assume that you have defined the following stopwords:<br />
Stopword<br />
busy machines<br />
294<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Stopword<br />
ltd<br />
The stopwords will not be searched, so the resulting search terms would be:<br />
Search Terms<br />
Incredible Busy Machines Ltd<br />
Incredible Busy Machines Limited<br />
IBM Ltd<br />
IBM Limited<br />
Fuzzy Search with Term Mappings<br />
Facts About Term Mappings<br />
Term mappings have the following characteristics:<br />
● Term mappings can be used to extend the search by adding additional search terms to the user input.<br />
Whenever the user enters a search term, the search term is expanded and synonyms, hypernyms, hyponyms,<br />
and so on are added. The result that is returned to the user contains additional records or documents related<br />
to the search term that may be useful to the user.<br />
● Term mappings are defined in a column table and can be changed at any time.<br />
The current term-mapping definition is applied when a search is started. The definition of term mappings<br />
does not change the data that is stored in the database tables (in contrast to the definition of synonyms in<br />
Text Analysis, where a change of synonyms requires a reload or reindexing of the text data).<br />
● Term mappings can be grouped.<br />
Each group of term mappings is identified by a list_id that is stored in the term-mapping table. By grouping<br />
term mappings it is possible to apply different sets of term mappings to different columns of a table. For<br />
example, you may want to use some term mappings when searching company names and other term<br />
mappings when searching documents. When starting a search, it is possible to specify the term-mapping<br />
list_ids that shall be applied to each column.<br />
● Term mappings can be assigned a weight.<br />
In this case, records that are found because of a term mapping will get a lower score than records found with<br />
the original user input. From the user's view, the result list is sorted in a more useful way.<br />
● Term mappings are defined as a unidirectional replacement.<br />
For a term-mapping definition of 'term1' -> 'term2', 'term1' is replaced with 'term2', but 'term2' is not replaced<br />
with 'term1'. This is helpful if you want a search with a hypernym to find all hyponyms, but not the other way<br />
round. If a bidirectional replacement is needed (as for synonyms), both directions have to be added to the<br />
term-mapping table.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 295
● Term mappings are language dependent.<br />
It is possible to define the language that a term mapping is valid for. You can also define term mappings for all<br />
languages by not setting a language.<br />
Use Cases<br />
Synonyms<br />
If you have a large database of company names, you might want to map the companies' legal forms.<br />
For example:<br />
Searching for You would also like to find With a weight of<br />
AG Aktiengesellschaft 1.0<br />
Ltd Limited 1.0<br />
As these are synonyms, the term mappings have to be added to the term-mapping table in both directions, as<br />
shown in the example below.<br />
Usually, synonym definitions get a weight of 1.0, because records found when the term mapping is applied are as<br />
good as records found with the original user input.<br />
Hypernyms, Hyponyms<br />
If you search with a hypernym, you might also find other documents related to this topic.<br />
For example:<br />
Searching for You would also like to find With a weight of<br />
car VW Golf 0.8<br />
As these are not synonyms, and a search with 'VW Golf' shall not return all documents about cars, the term<br />
mapping is added to the term-mapping table in this direction only.<br />
Format of the Term-Mapping Table<br />
Column Name Type Primary Key Description Comment<br />
MAPPING_ID VARCHAR(32) x Primary key For example, a GUID<br />
LIST_ID VARCHAR(32) Term-mapping list ID Used to group term<br />
LANGUAGE_CODE CHAR(2) Language code<br />
296<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
(ISO2)<br />
mappings<br />
NULL: term mapping<br />
is valid for all<br />
languages<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Column Name Type Primary Key Description Comment<br />
TERM_1 NVARCHAR(200) Term 1, the term to<br />
be replaced<br />
TERM_2 NVARCHAR(200) Term 2, the term<br />
that replaces term 1<br />
WEIGHT DECIMAL Weight, 0.0
FUZZY(0.8,<br />
'termMappingTable=termmappings,termMappingListId=01,textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID COMPANYNAME<br />
1.0 2 <strong>SAP</strong> Aktiengesellschaft<br />
0.9 1 <strong>SAP</strong> AG<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies<br />
WHERE CONTAINS(companyname, 'sap ag',<br />
FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId=01,textSearch=co<br />
mpare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID COMPANYNAME<br />
1.0 1 <strong>SAP</strong> AG<br />
0.9 2 <strong>SAP</strong> Aktiengesellschaft<br />
To activate language-specific term mappings, you must provide the language parameter:<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM companies<br />
WHERE CONTAINS(companyname, 'sap ag',<br />
FUZZY(0.8,'termMappingTable=TERMMAPPINGS,termMappingListId=01,textSearch=co<br />
mpare'), language('de'))<br />
ORDER BY score DESC, id;<br />
Note: In this case, all term mappings where language_code is set to 'de' or empty will be used. Any term<br />
mappings with other language codes will be ignored.<br />
Fuzzy Search on DATE Columns<br />
A fuzzy search on DATE columns supports two types of error:<br />
● Date-specific typos<br />
● Dates lying within a user-defined maximum distance<br />
Score Calculation for Typos<br />
Instead of using Levenshtein distance or other string-compare algorithms, the following date-specific typos and<br />
errors are defined as similar:<br />
1. One wrong digit at any position (for example, 2011-08-15 instead of 2011-08-25). This type of error gets a<br />
score of 0.90.<br />
2. Two digits interchanged within one component (day, month, or year) (for example, 2001-01-12, 2010-10-12, or<br />
2010-01-21 instead of 2010-01-12). This type of error gets a score of 0.85.<br />
3. Month and day interchanged (US versus European date format) (for example, 2010-10-12 instead of<br />
298<br />
2010-12-10). This type of error gets a score of 0.80.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Only one of these errors is allowed. Dates with more than one error are not considered similar, so the score is 0.0.<br />
Dates with a score less than the fuzzySimilarity parameter are not returned.<br />
Example:<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM dates<br />
WHERE CONTAINS(dateofbirth, '2000-01-10', FUZZY(0.8))<br />
ORDER BY score DESC;<br />
For this example we get:<br />
2000-01-09 -> 0.00 (not returned to the user)<br />
2000-01-10 -> 1.00<br />
2000-01-11 -> 0.90<br />
2000-01-12 -> 0.90<br />
...<br />
2000-01-21 -> 0.00 (not returned to the user)<br />
...<br />
2000-10-01 -> 0.80<br />
Score Calculation for Date Distance<br />
The maximum allowed distance between dates can be defined using the search option 'maxDateDistance', which<br />
defines a number of days.<br />
The default for this option is 0, that is, the feature is disabled. This is shown in the following example:<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM dates<br />
WHERE CONTAINS(dateofbirth, '2000-01-10', FUZZY(0.95, 'maxDateDistance=5'))<br />
ORDER BY score DESC;<br />
This query returns all dates between 2000-01-05 and 2000-01-15.<br />
The fuzzy score for dates is calculated as follows:<br />
The identical date gets a score of 1.0.<br />
The date that is maxDateDistance days away from the search input gets a score that equals the fuzzySimilarity<br />
parameter (0.95 in the example above).<br />
The score of dates between the identical date and maxDateDistance is calculated as a linear function between the<br />
two dates defined above. In other words, for each day the score is reduced by ((1-fuzzySimilarity) /<br />
maxDateDistance).<br />
For dates outside the range of maxDateDistance, the score is 0.0.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 299
Therefore, for the example above we get:<br />
2000-01-04 -> 0.00<br />
2000-01-05 -> 0.95<br />
2000-01-06 -> 0.96<br />
...<br />
2000-01-09 -> 0.99<br />
2000-01-10 -> 1.0<br />
2000-01-11 -> 0.99<br />
2000-01-12 -> 0.98<br />
...<br />
2000-01-15 -> 0.95<br />
2000-01-16 -> 0.00<br />
The distance between dates is calculated following the rules of the Gregorian calendar.<br />
The special case 'fuzzySimilarity = 1.0' and maxDateDistance=n is allowed and returns all dates within a range of n<br />
days with a rank of 1.0.<br />
Dates That Meet Both Conditions<br />
If a date meets the conditions of a typo and also the conditions of the maxDateDistance parameter, two scores<br />
are calculated for the same date. In this case, the score() function returns the highest of both scores. This is<br />
shown in the following example:<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM dates<br />
WHERE CONTAINS(dateofbirth, '2000-01-10', FUZZY(0.8, 'maxDateDistance=5'))<br />
ORDER BY score DESC;<br />
This query returns the following:<br />
2000-01-04 -> 0.00<br />
2000-01-05 -> 0.80<br />
2000-01-06 -> 0.84<br />
2000-01-07 -> 0.88<br />
2000-01-08 -> 0.92<br />
2000-01-09 -> 0.96<br />
2000-01-10 -> 1.0<br />
300<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
2000-01-11 -> 0.96<br />
2000-01-12 -> 0.92<br />
2000-01-13 -> 0.90<br />
2000-01-14 -> 0.90<br />
2000-01-15 -> 0.90<br />
2000-01-16 -> 0.90<br />
Search Rules<br />
Overview<br />
With fuzzy search in <strong>SAP</strong> <strong>HANA</strong>, you can search for structured database content that is similar to the user input.<br />
In this case, the user input and the records in the database are nearly the same but differ in their spelling (for<br />
example, typing errors) or contain additional information (for example, additional or missing terms).<br />
Among the use cases of fuzzy search on structured data, there is the prevention of duplicate records. New<br />
database records can be checked for similar and already existing records in real time, just before the new record<br />
is saved.<br />
For example, before saving a new customer to the database, the application checks for similar customers that<br />
may be duplicates of the newly entered customer. The application does some searches and then presents to the<br />
user any existing customers that are similar to the user input. The user then decides whether to create a new<br />
customer (because the records presented are similar, but not really duplicates) or to accept one of the existing<br />
customers and continue with this customer record.<br />
The searches performed by the application are defined by business rules that define when two customers are<br />
similar. For example, two customers may be considered similar by the application as soon as one of the following<br />
conditions is true:<br />
1. The customers' names and addresses are similar.<br />
2. The customers' last names and addresses are identical but the first names are different (may be persons<br />
living in the same household).<br />
3. The customers' names are similar and the dates of birth are identical.<br />
These rules can be hardcoded in the application by writing three SELECT statements that do the three searches<br />
defined above. Whenever the requirements for the search rules change, the application code has to be changed,<br />
tested and deployed to the productive system. This may be costly in terms of time and development resources<br />
needed.<br />
Alternatively, the application can use search rules to store the rules as a configuration object in the <strong>SAP</strong> <strong>HANA</strong><br />
database. Instead of embedding the rules in SELECT statements that are part of the application code, the<br />
application has to call a database procedure only to process all rules defined in the configuration object.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 301
When the business requirements change, only the search rule definition in the configuration object has to be<br />
changed, tested, and deployed. The interface to the database procedure that is called by the application stays<br />
unchanged. So without any change to the application code, the definition of the search rules is changed and the<br />
user immediately gets search results according to the new requirements. This results in much less effort and<br />
more flexibility when changing search rules.<br />
Supported Database Objects<br />
You can search on attribute views. The views have to be modeled using the <strong>SAP</strong> <strong>HANA</strong> studio and have to be<br />
stored as objects in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
Other database objects, such as row tables, column tables, calculation views, or analytic views, are not supported.<br />
Important Terms<br />
A search rule set is the configuration object that is stored in the <strong>SAP</strong> <strong>HANA</strong> repository and that contains the<br />
definition of the search rules. When the database procedure is called to do a search, a search rule set is executed.<br />
This means that all rules that are defined in the search rule set are executed.<br />
A search rule defines a condition when two records – the user input and a record in the database – are<br />
considered similar. Each rule in a search rule set is converted to a SELECT statement and is executed when the<br />
search rule set is processed.<br />
Creating Search Rule Sets<br />
You created a workspace and a project in the <strong>SAP</strong> <strong>HANA</strong> studio. In this workspace, you created a package that will<br />
contain your rule set.<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> modeler, open the Project Explorer view and navigate to your package.<br />
2. From the context menu of your package, select New Other Search Rule Set .<br />
3. Enter a file name for your rule set. The file has to have the extension .searchruleset.<br />
4. Open and edit the search rule set in the search rule set editor. See Working with the Search Rule Set Editor<br />
[page 302]<br />
5. Define the attribute view, key columns, score selection parameter, stopwords, and term mappings. See<br />
Configuring Search Rule Sets [page 303]<br />
6. From the context menu of your package or search rule, choose Team Activate .<br />
You can now execute a search with the rule set. See Executing a Search With a Rule Set [page 304]<br />
Working with the Search Rule Set Editor<br />
● To open a rule set in the editor, double-click a rule set file or, from the context menu, select Open With<br />
Search Rule Set Editor .<br />
● To add new nodes, children or siblings, you can use the context menu of each node.<br />
For example, you can a new key column node in the following ways:<br />
○ Select the attribute view node and, in the context menu, choose New Key Column.<br />
○ Select a key column node and, in the context menu, choose New Key Column.<br />
● To delete a node from the search rule set, select the node and, from the context menu, select Delete.<br />
302<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
This deletes the node and all its child nodes.<br />
● To change the order of nodes or to move nodes to other parent nodes, you can drag and drop the nodes.<br />
With the <strong>SAP</strong> <strong>HANA</strong> studio running on Microsoft Windows, you can copy nodes below the same parent node<br />
or even to another parent node by pressing CTRL while dragging.<br />
● To change properties, click on the value of the property in the Properties view and enter the new value.<br />
Each node contains a set of properties that define the behavior of the search rules. Node properties are<br />
displayed in the Properties view of the <strong>SAP</strong> <strong>HANA</strong> studio when a node is selected in the tree. If the Properties<br />
view is not displayed, you can open it by choosing Window Show View Properties .<br />
Note: Some node properties refer to database objects or to column names. These properties are<br />
case-sensitive so you have to enter all names in the correct notation.<br />
Configuring Search Rule Sets<br />
● Define the attribute view.<br />
The search rule set searches on an attribute view that is modeled using the <strong>SAP</strong> <strong>HANA</strong> studio. The attribute<br />
view to be used is defined in the attribute view node of the search rule set. The name property contains the<br />
name of the attribute view. The FQN notation (fully qualified name) is used to specify the view.<br />
● Define the key columns and the score selection parameter.<br />
A search may return the same record more than once because it matches more than one rule.<br />
To enable the search to return each record only once, key columns must be defined in a way that makes<br />
records in the result set unique. For an attribute view, there is no definition of key columns available, so the<br />
key columns have to be defined for each search rule set.<br />
The key columns are a set of one or more columns of the attribute view that clearly identify a record in the<br />
view. So the key columns are similar to the primary key columns of a database table.<br />
As for primary keys, LOB types (BLOB, CLOB, NCLOB, TEXT) are not allowed as key columns.<br />
Note: It is possible to create an invalid key column definition that does not make the result set unique.<br />
In this case, when running a search, an error is raised when records returned by a single rule are not<br />
unique.<br />
By default, each search rule set contains one key column node below the attribute view node. If more columns<br />
are needed to make records unique, more key column nodes can be added below the attribute view node.<br />
In each key column node enter the name of the attribute view column in the properties panel.<br />
In addition to the key columns, you have to define how the result set shall be made unique. Records returned<br />
by more than one rule usually have different scores assigned. Only one combination of score and rule name<br />
can be returned in the result set.<br />
The score selection parameter defines whether the values with the highest score or the values found with the<br />
first matching rule are returned.<br />
The score selection parameter is defined in the properties panel of the rule set node.<br />
● Define stopwords and term mappings.<br />
To use stopwords and term mappings in a search rule set, the configuration options have to be added to the<br />
rule set.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 303
First, open the context menu of the Search Rule Set node and select New Stopwords (table-based) or New<br />
Term Mappings (table based).<br />
In the properties of the new nodes, you can define the stopword table and term mapping table that is used.<br />
On the Stopwords (table-based) or Term Mappings (table-based) node, select New Column to enable the<br />
stopwords or term mappings on a column. In the properties panel, you can define the name of the column<br />
where stopwords and term mappings shall be applied.<br />
Below the Column nodes, create new List ID nodes (open the context menu and select New List ID). In each<br />
list ID node, you can configure a stopword or term mapping list that is applied on the column.<br />
The stopword and term mapping settings are valid for a given column in all rules.<br />
Executing a Search With a Rule Set<br />
<strong>HANA</strong> exports a new built-in function: SYS.EXECUTE_SEARCH_RULE_SET, with which you can execute a<br />
previously defined search rule set.<br />
The function has one parameter, which is an XML string to run the search. Within this XML, you have to specify:<br />
● The ruleset that should be executed<br />
● The way the result will be returned<br />
● The limitation of the result<br />
● The input values<br />
The EXECUTE_SEARCH_RULE_SET method returns by default a ResultSet object. This object contains all the<br />
columns from the referenced attribute view plus additional columns _SCORE and _RULE_ID. Alternatively, the<br />
EXECUTE_SEARCH_RULE_SET can write the result into a results table that needs to be created by the user.<br />
For code samples of SYS.EXECUTE_SEARCH_RULE_SET calls, see Search with a Rule Set - Code Samples [page<br />
304].<br />
Transaction Isolation Level<br />
The EXECUTE_SEARCH_RULE_SET function creates one SELECT statement for each of the rules and runs the<br />
statements independent of each other. The statements are executed in the transaction context of the calling<br />
application and use the same isolation level as the application. The isolation level has an influence on the results of<br />
the EXECUTE_SEARCH_RULE_SET function when there are other transactions running in parallel that change the<br />
contents of the database tables.<br />
When the isolation level 'READ COMMITTED' is used, each of the SELECT statements of the search rule set sees<br />
all changes that have been committed at the time the execution of the SELECT statement begins. So, for example,<br />
the second rule of a rule set may see a new record that was not committed when the first rule has been executed.<br />
In this case, the new record may be returned by the 'wrong' rule and the user gets an incorrect result.<br />
When the isolation levels 'REPEATABLE READ' or 'SERIALIZABLE' are used, all SELECT statements see the same<br />
state of the database. So the results returned by EXECUTE_SEARCH_RULE_SET are always correct.<br />
Search with a Rule Set - Code Samples<br />
Executing a search and returning the result as a ResultSet:<br />
CALL SYS.EXECUTE_SEARCH_RULE_SET('<br />
<br />
<br />
-- specifies the SearchRuleSet<br />
Herbert -- specifies the input value<br />
for column FIRSTNAME<br />
304<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Hofmann -- specifies the input value<br />
for column LASTNAME<br />
<br />
');<br />
Executing a search and writing the result to a column table provided by the user:<br />
--First create the result table<br />
set schema MY_SCHEMA;<br />
CREATE COLUMN TABLE MY_RESULT_TABLE (<br />
_SCORE FLOAT,<br />
_RULE_ID VARCHAR(255),<br />
"FIRSTNAME" TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON,<br />
"LASTNAME" TEXT FUZZY SEARCH INDEX ON FAST PREPROCESS ON<br />
};<br />
-- Afterwards you can execute the search using the created result table.<br />
CALL SYS.EXECUTE_SEARCH_RULE_SET('<br />
<br />
<br />
-- specifies the SearchRuleSet<br />
-- specifies the schema of<br />
the result table<br />
-- specifies the name of the<br />
result table<br />
Herbert -- specifies the input value<br />
for column FIRSTNAME<br />
Hofmann -- specifies the input value<br />
for column LASTNAME<br />
<br />
');<br />
-- get the result<br />
select * from MY_RESULT_TABLE;<br />
Limiting the number of rows returned by a search:<br />
Note: When calling the system procedure EXECUTE_SEARCH_RULE_SET, the application can define the<br />
maximum number of rows that are returned by setting a limit parameter. By default, this parameter is<br />
undefined, which means that an unlimited number of rows is returned. The limitation takes place after<br />
each rule and in the end when all rules are performed. In the following example, a maximum number of<br />
100 rows will be returned. You can use this parameter with the ResultSet object and with the custom<br />
result table.<br />
-- run the search<br />
CALL SYS.EXECUTE_SEARCH_RULE_SET('<br />
<br />
<br />
billy<br />
smith<br />
<br />
');<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 305
Frequently Asked Questions<br />
Why are there results with a score lower than the requested fuzzySimilarity?<br />
In text fields, the parameter fuzzySimilarity sets the minimum similarity that a token has to match to be included<br />
in the search result. All other fuzzy search operations (for example, applying term mappings, considering<br />
stopwords, abbreviationSimilarity) can influence the score that you will see.<br />
How many misspellings are allowed with a particular fuzzySimilarity?<br />
This question is not easy to answer. The scoring algorithm is not linear to the number of misspellings; the position<br />
of the misspelling is also important. You can use the following example to familiarize yourself with it.<br />
DROP TABLE test;<br />
CREATE COLUMN TABLE test<br />
(<br />
id INTEGER PRIMARY KEY,<br />
companyname SHORTTEXT(200) FUZZY SEARCH INDEX ON<br />
);<br />
INSERT INTO test VALUES ('1','abc');<br />
INSERT INTO test VALUES ('2','abx');<br />
INSERT INTO test VALUES ('3','xbc');<br />
INSERT INTO test VALUES ('4','axc');<br />
INSERT INTO test VALUES ('5','abcx');<br />
INSERT INTO test VALUES ('6','xabc');<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test<br />
WHERE CONTAINS(companyname, 'abc',<br />
FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=1'))<br />
ORDER BY score DESC, id;<br />
SCORE ID COMPANYNAME<br />
1 1 abc<br />
0.89 5 abcx<br />
0.82 2 abx<br />
0.75 6 xabc<br />
0.61 3 xbc<br />
0.61 4 axc<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, * FROM test<br />
WHERE CONTAINS(companyname, 'abcx',<br />
FUZZY(0.5,'textSearch=compare,bestMatchingTokenWeight=1'))<br />
ORDER BY score DESC, id;<br />
SCORE ID COMPANYNAME<br />
1 5 abcx<br />
0.89 1 abc<br />
306<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
SCORE ID COMPANYNAME<br />
0.88 6 xabc<br />
0.75 3 abx<br />
0.59 3 xbc<br />
0.59 4 axc<br />
How do I find out if the fuzzy search index is enabled for column x?<br />
See Basic Examples.<br />
How do I enable the fuzzy search index for a particular column?<br />
See Basic Examples.<br />
The additional data structures will increase the total memory footprint of the loaded table. In unfavorable cases<br />
the memory footprint of the column can double.<br />
How can I see how much memory is used for a fuzzy search index?<br />
See Memory Usage [page 267].<br />
Is the score between request and result always stable for TEXT columns?<br />
It depends on how you look at the topic. The algorithm is indeed deterministic, but you need to take all parameters<br />
into account. Cases can be constructed where a small change in the fuzzySimilarity will change the rank between<br />
the same strings.<br />
Why is this? The fuzzySimilarity is the minimum score that tokens need to reach to be considered for the result. If<br />
you use andThreshold or the keyword "OR" in your search, not all tokens have to reach the fuzzySimilarity to be<br />
part of the result. This can lead to a change in the total score if you change the fuzzySimilarity. Let us look at an<br />
example:<br />
DROP TABLE companies;<br />
CREATE COLUMN TABLE companies<br />
(<br />
id INTEGER PRIMARY KEY,<br />
companyname SHORTTEXT(200)<br />
);<br />
INSERT INTO companies VALUES(1, 'aktien gesellschaft');<br />
INSERT INTO companies VALUES(2, 'aktiv gesellschaft');<br />
Important: The similarity between "aktien" and "aktiv" is 0.77.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 307
If the fuzzySimilarity is lower than 0.77, the token scoring will be part of the result score. If the fuzzySimilarity is<br />
higher than 0.77, the token scoring will not be considered, so the total scoring will be lower.<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, id, companyname<br />
FROM companies<br />
WHERE CONTAINS(companyname, 'aktiv OR gesellschaft', FUZZY(0.75,<br />
'textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID COMPANYNAME<br />
1 2 aktiv gesellschaft<br />
0.89 1 aktien gesellschaft<br />
SELECT TO_DECIMAL(SCORE(),3,2) AS score, id, companyname<br />
FROM companies<br />
WHERE CONTAINS(companyname, 'aktiv OR gesellschaft', FUZZY(0.80,<br />
'textSearch=compare'))<br />
ORDER BY score DESC, id;<br />
SCORE ID COMPANYNAME<br />
1 2 aktiv gesellschaft<br />
0.71 1 aktien gesellschaft<br />
11.3 Building Search Apps<br />
11.3.1 Introduction to the UI Toolkit for Info Access<br />
The UI toolkit for <strong>SAP</strong> <strong>HANA</strong> Info Access provides UI building blocks for developing browser-based search apps on<br />
<strong>SAP</strong> <strong>HANA</strong>. Such applications provide real-time information access and faceted search features for huge volumes<br />
of structured and unstructured text data.<br />
The toolkit enables a freestyle search of a <strong>SAP</strong> <strong>HANA</strong> attribute view, displaying and analyzing the result set. The<br />
toolkit provides UI elements (widgets) such as a search box, a result list with a detailed view, and charts for basic<br />
analytics on the result set. The widgets are interconnected and adapt in real-time to user entries and mouse-over<br />
(hover) selections.<br />
The toolkit is based on HTML5 and JavaScript libraries such as JQuery/JQueryUI, d3 (Data Driven Documents),<br />
and Tempo. The widgets use the <strong>SAP</strong> <strong>HANA</strong> Info Access HTTP service. You do not need an additional layer to run<br />
the UI; <strong>SAP</strong> <strong>HANA</strong> and a Web browser are sufficient. The toolkit is tested on Mozilla Firefox 17. It also runs on<br />
Microsoft Internet Explorer 9 in standard mode and Google Chrome.<br />
Along with the actual toolkit (the widgets), we deliver a fully operational demo Web app built using this toolkit. The<br />
demo app enables you to explore a search application dealing with a set of sample data for electronic products.<br />
You can use the demo app as a template or for reference when you start developing your own app.<br />
You can, for example, use the demo site to easily connect your own data and compose your Web site. To create a<br />
search application this way, it is sufficient to have experience in HTML and to have read this documentation. For<br />
308<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
advanced customizing and layout of the site, more in-depth knowledge of CSS and the above-mentioned<br />
JavaScript libraries is required.<br />
What is the <strong>SAP</strong> <strong>HANA</strong> Info Access HTTP Service?<br />
In the first place, <strong>SAP</strong> <strong>HANA</strong> is a database. It stores any type of raw data in its tables: master data, transactional<br />
data, numbers, texts, and so on. But <strong>SAP</strong> <strong>HANA</strong> can do more than a classic database. <strong>SAP</strong> <strong>HANA</strong> also enables you<br />
to turn raw data into meaningful information.<br />
For the world of numbers, there are the analytics features of <strong>SAP</strong> <strong>HANA</strong>. By joining, aggregating, and calculating,<br />
they can turn raw facts and numbers into meaningful measures and key figures.<br />
For the world of texts, there are the full text search and text analysis features of <strong>SAP</strong> <strong>HANA</strong>. By tokenizing,<br />
stemming, normalizing, and analyzing semantically, they can turn a set of strings into a structured and searchable<br />
text corpus.<br />
So there is meaningful information in <strong>SAP</strong> <strong>HANA</strong>. But it is still not instantly available to business end users. SQL is<br />
a very powerful tool for accessing and processing <strong>SAP</strong> <strong>HANA</strong> information. However, it operates on a very<br />
technical level deep down in the stack and far from an end user UI.<br />
This is where the info access service of <strong>SAP</strong> <strong>HANA</strong> steps in. As long as you only need read-access, meaning<br />
search or basic analytics, the service provides shortcuts to Web and mobile UIs.<br />
<strong>SAP</strong> <strong>HANA</strong> Info Access Architecture<br />
The <strong>SAP</strong> <strong>HANA</strong> info access HTTP service wraps search and analytic SQL queries and exposes them through an<br />
HTTP interface. On the UI layer, Info Access offers the HTML5 development kit including UI widgets and Web site<br />
templates. No intermediate layer is required. To provide Info Access apps to your users, you only need <strong>SAP</strong> <strong>HANA</strong><br />
and a Web browser.<br />
11.3.2 Installing the Service and the Toolkit<br />
The UI toolkit and the service are part of the default <strong>SAP</strong> <strong>HANA</strong> shipment, but they are not installed automatically.<br />
They are shipped as separate delivery units that you can import and activate quickly as described below.<br />
Importing the Delivery Units<br />
● <strong>SAP</strong> <strong>HANA</strong> Appliance Software, support package stack (SPS) 05 or higher, running on a server.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 309
● <strong>SAP</strong> <strong>HANA</strong> studio and <strong>SAP</strong> <strong>HANA</strong> client installed on your local machine.<br />
1. To import the UI toolkit and the service, in the <strong>SAP</strong> <strong>HANA</strong> studio, choose the Modeler perspective and select<br />
your database instance.<br />
2. From the menu, choose File Import .<br />
3. Select <strong>HANA</strong> Content Delivery Unit and choose Next.<br />
4. Select Client and browse for the HCO_INA_UITOOLKIT.tgz delivery unit.<br />
The delivery units can be found on the <strong>SAP</strong> <strong>HANA</strong> host under SYS/global/hdb/content.<br />
5. Select both actions and choose Finish.<br />
6. Perform the same import procedure for the HCO_INA_SERVICE.tgz delivery unit.<br />
7. In the Navigator pane, under Content, check that the following packages are available:<br />
sap\bc\ina\uitoolkit<br />
sap\bc\ina\demos\epm<br />
sap\bc\ina\service\v2<br />
8. To get started developing apps using the toolkit, set up an application project.<br />
Related Links<br />
i031349364909774.ditamap<br />
Registering and Activating the Info Access Service<br />
1. To register the service, switch to the Lifecycle Management perspective of the <strong>SAP</strong> <strong>HANA</strong> studio and select<br />
your database instance.<br />
2. Choose the Configuration tab page and expand xsengine.ini\application_container.<br />
3. Double-click the application_list line and, under the System column, add the entry<br />
InformationAccess.<br />
Caution: Once InformationAccess is running, <strong>SAP</strong> <strong>HANA</strong> data is exposed by an HTTP service (port<br />
80).<br />
4. To restart <strong>SAP</strong> <strong>HANA</strong> XS, choose the Landscape tab page.<br />
5. From the context menu of the xsengine service, choose Kill...<br />
The service stops completely and restarts automatically.<br />
Importing the Demo Data<br />
1. Go to the <strong>SAP</strong> Code Exchange Web page of the UI toolkit.<br />
2. From the Documents tab page, download the epm_data.zip archive.<br />
3. Follow the instructions in the readme.txt file contained in the archive.<br />
Related Links<br />
<strong>SAP</strong> Code Exchange Web page of the UI toolkit<br />
11.3.3 <strong>Get</strong>ting to Know the Demo App<br />
You can now explore what an app built using the UI toolkit looks and feels like. Start the sample UI in a Web<br />
browser by opening the following URL:<br />
http://:80/sap/bc/ina/demos/epm/search.html<br />
310<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Example: http://hana1.acme.corp:8001/sap/bc/ina/demos/epm/search.html<br />
Start exploring the UI.<br />
The demo app consists of a header row, a column on the left, and a large content area on the right. The column on<br />
the left contains some widgets; the search box and some charts. The charts are used for displaying the count of<br />
result items with distinct values. In the EPM example, it is the count of sold products by category and by currency.<br />
The content area on the right is for displaying an enlarged view of one of the widgets, the result list is enlarged at<br />
page load.<br />
The app starts with a search for all. By typing in the search box or filtering in the charts, you can refine the result<br />
set. The results are displayed in the list ranked by relevancy.<br />
From the right margin of the page, you can pull in the facet repository containing all configured facets that are not<br />
displayed in the column and the content pane. Facets are the widgets, such as the results list and charts, that<br />
display the dimensions of the result set.<br />
You can drag and drop all facets to any position on the UI, be it the column, the content area or the facet<br />
repository. When a chart is enlarged in the content pane, you can change the chart type with a click.<br />
11.3.4 <strong>Get</strong>ting to Know the Demo HTML<br />
The structure and content of the UI are defined in the search.html file. Open the search.html file using the<br />
HTML editor. Familiarize yourself with the structure of the HTML.<br />
Partly collapsed, search.html looks like this:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 311
In the head area and at the end of the HTML, there is meta data and references to the various JavaScript libraries<br />
and CSS used by the UI.<br />
The body of the HTML contains the UI's header bar with the title text and the alert bar for displaying<br />
messages. The rest of the body is the workarea. A workarea connects to a <strong>SAP</strong> <strong>HANA</strong> attribute view and<br />
serves as a container for all other widgets on the page. The workarea is divided into the facetPane, the<br />
contentPane, and the facetrepository.<br />
The facetPane starts with the searchbox followed by a facetcolumn and the facetpane. The<br />
workareaitem widgets inside the column and the pane are only placeholders for facets of the repository that<br />
the user can shuffle around at runtime.<br />
Inside the facetrepository, there are the actual workareaitem widgets. For switching between different<br />
chart types, there are the switchbox widgets. The last widget in the repository is the resultlist.<br />
11.3.5 Preparing Your Source Data<br />
Before you start to build your information access application, you need to have a clear understanding of who will<br />
use it and for what purpose. Once you are sure which content you need to enable for access, prepare this data as<br />
described here. Then you define how the content is to be displayed and which interactive navigation attributes are<br />
to be provided.<br />
Ensuring Full Text Indexing<br />
Make sure that a full-text index is created for each of your table columns that contains human-readable text data<br />
that is suitable for a freestyle search. The index structure is attached to the column and is leveraged to identify<br />
texts that contain the search terms. The full text index is automatically updated when new records are entered in<br />
the table.<br />
312<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
Along with the full text index, you can also trigger a text analysis that extracts entities, such as dates or people,<br />
from the text and, therefore, enriches the set of attributes.<br />
Related Links<br />
Creating Full Text Indexes [page 235]<br />
When you create a TEXT or SHORTTEXT column in a table, <strong>SAP</strong> <strong>HANA</strong> automatically creates a corresponding<br />
full text index. However, for columns of other data types, you must manually create and define any necessary<br />
full text indexes.<br />
Text Analysis [page 242]<br />
Checking the Settings in <strong>SAP</strong> <strong>HANA</strong> Studio<br />
Technical search in <strong>SAP</strong> <strong>HANA</strong> may not be enabled. To check if it is enabled, proceed as follows:<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio menu, choose Window Preferences Modeler Search Options .<br />
2. Check if the Enable Search Attributes option is selected. If not, select it and choose Apply and OK.<br />
Note: You must make this setting in every <strong>SAP</strong> <strong>HANA</strong> studio that you use to model views for search.<br />
Modeling Your Search Content<br />
For each app user, you have created a named database user with the following authorizations:<br />
● Object privileges: SELECT on database schemas and .<br />
● Analytic privileges: For and for the attribute view you want to visualize in the app.<br />
In the <strong>SAP</strong> <strong>HANA</strong> modeler, create an attribute view of type standard using the tables that you want to enable for<br />
the search. Create joins and add the attributes you want to use for searching and displaying.<br />
Note: You can also join additional attributes derived from the text analysis.<br />
To enable certain attributes for the search, proceed as follows:<br />
1. In the Output view, select the attributes.<br />
Note: The searchable attributes must not be calculated attributes nor have lower case letters in their<br />
names.<br />
2. In the lower area of the Properties tab, select the Information Access category.<br />
3. Set the <strong>Free</strong>style Search property to true.<br />
In the Information Access category, you can make additional search-specific settings.<br />
The Weights for Ranking setting (between 0.0 and 1.0, default 0.5) influences the ranking of items in the results<br />
list. The higher the weight of the attribute, the higher up in the list an item with a hit in this attribute is positioned.<br />
The Fuzziness Threshold setting (between 0.0 and 1.0, default 0.8) defines the grade of error tolerance for a<br />
search on this attribute. The higher the threshold, the more exact the search terms must hit the text to produce a<br />
result.<br />
Note: Do not forget to activate the attribute view.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 313
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Modeling Views<br />
FUZZY Search [page 256]<br />
Fuzzy Search is a fast and fault-tolerant search feature for <strong>SAP</strong> <strong>HANA</strong>. A fuzzy search returns records even if<br />
the search term contains additional or missing characters or other types of spelling errors.<br />
11.3.6 Connecting Your Source Data<br />
You can connect any search-enabled <strong>SAP</strong> <strong>HANA</strong> attribute view to the app by referencing the view and its<br />
attributes directly in your HTML file.<br />
To reference the attribute view and its schema in the HTML, enter their names in the workarea widget:<br />
<br />
data-entityset is the view name. data-schema is the database schema (catalog) in which the activated<br />
attribute view resides. The data-aggregationdimension is used as basis for counting items with distinct<br />
values. Enter an attribute that has unique values, for example, the primary key.<br />
For chart facets that display the aggregates of attribute values, for example the grouped bar chart, enter the<br />
attribute names here:<br />
<br />
In the grouped bar chart example, data-dimension-line is the attribute whose distinct value count is to be<br />
displayed as the bars. The data-dimension-x attribute is displayed as an additional dimension inside the<br />
chart as a group of bars. data-dimension-y is the measurement that is displayed on the y-axis defining the<br />
height of the single bars. In the search app, the only measurement available is the distinct values count ($count)<br />
of the attribute defined in data-dimension-line.<br />
In a simple bar or pie chart, the data-dimension parameter contains the attribute whose distinct value count<br />
is to be displayed<br />
To define the attributes to be displayed in a result list entry, enter the attribute names here:<br />
11.3.7 Defining the Page Layout<br />
Now that your source data is prepared and connected, you can form your UI using the search.html template.<br />
You may want to start by arranging the available widgets on your site. To place the column, the panes, and the<br />
facets within them, copy, move, or remove the corresponding HTML blocks.<br />
First, place the facet pane and its column(s) as well as the content pane. The panes and the columns inside are<br />
displayed from left to right on the UI in the same order as in the HTML. Only one content pane is allowed.<br />
Typically, a maximum of three facet columns are used. The facet repository is always last in the HTML.<br />
The search box and the facets inside the facet columns are next. The search box can span the entire pane across<br />
multiple columns. Place as many placeholder work area items as you want to have slots in a column. Inside the<br />
content pane, only one placeholder is allowed. Make sure that the data-target-position count is<br />
continuously set across the facet columns and the content pane.<br />
The facet repository holds the actual facets, meaning the chart switch boxes and the result list. The datasource-position<br />
parameter defines their position inside the facet repository as well as inside the columns<br />
and the content pane at page load.<br />
If the source position equals the target position, the respective facet replaces the placeholder in the columns and<br />
pane. If there are two or more facets with the same source position number, only the first one in the HTML<br />
replaces the placeholder. In the facet repository, all defined facets are available in the order of the source position<br />
or their appearance in the HTML. At runtime, the user can drag and drop the facets.<br />
At least one facet pane and content pane are required for the facet repository and free drag-and-drop. However,<br />
you could also build a minimal static UI with a workarea containing just a search box and a result list, for example.<br />
You can even integrate single widgets into other sites.<br />
Related Links<br />
workareaitem [page 316]<br />
11.3.8 Configuring the Widgets<br />
The widgets are based on jQuery UI. In the HTML, you can customize the single widgets to a certain degree using<br />
parameters. The common parameter data-sap-widget defines the type of the widget.<br />
Each widget type has its own set of parameters. The widgets and their parameters are listed in the order of<br />
appearance in the demo HTML file.<br />
header<br />
Parameter Name Default Value Description<br />
data-title none Title text in the header bar of the UI.<br />
data-helphref none Reference to the documentation for the users of your application.<br />
workarea<br />
Parameter Name Default<br />
Value<br />
Description<br />
data-title none This title is not displayed on the UI.<br />
data-packagename none Name of the database package in which the attribute view was created.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 315
Parameter Name Default<br />
Value<br />
Description<br />
data-entityset none Name of the attribute view.<br />
data-schema _SYS_BIC Name of the database schema (catalog) in which the activated attribute<br />
view resides. The schema _SYS_BIC is default because your activated<br />
dataaggregationdimen<br />
sion<br />
dataaggregationsorto<br />
rder<br />
Related Links<br />
Connecting Your Source Data [page 314]<br />
searchbox<br />
attribute views usually end up in this schema.<br />
none Primary key attribute of the items you want to search and display. The<br />
unique key is used to identify items for the result list and to count items<br />
with distinct values for the charts.<br />
DESC Descending or ascending (ASC) order for sorting the counts in the<br />
Parameter Name Default Value Description<br />
charts. This setting is inherited by all charts if you do not set a sort order<br />
there.<br />
data-maxinputlength 255 Maximum number of characters that users can enter in the<br />
search box.<br />
workareaitem<br />
Parameter Name Default Value Description<br />
data-title none This title is displayed on the UI as the facet headline. If the<br />
workareaitem is a placeholder, the title is used as<br />
alternative text. The alternative is displayed if the<br />
placeholder is not replaced by an actual workareaitem<br />
at runtime.<br />
data-target-position 0 Position of a placeholder workareaitem on the UI in the<br />
facet or content pane. The count starts on the upper left of<br />
the UI.<br />
data-source-position 0 Position of the actual workareaitem on the UI in the<br />
facetrepository<br />
Parameter Name Default Value Description<br />
data-children-draghandle<br />
316<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
facet repository on the right. On page load, the<br />
workareaitem placeholders are replaced by the actual<br />
workarea items whose source positions match the target<br />
positions.<br />
body Defines the area where a user can grab a facet for drag and drop.<br />
body means the complete facet, header means the facet's<br />
header bar only.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
switchbox<br />
Parameter Name Default Value Description<br />
data-activeindex 0 Defines which chart contained in the switchbox is displayed on page<br />
load. 0 means the first one, 1 the second, and so on.<br />
chart<br />
Parameter Name Default Value Description<br />
data-toplarge none Defines how many bars or pie segments are displayed when the<br />
chart is enlarged.<br />
data-dimension none Attribute whose distinct value count is to be displayed in a<br />
simple bar or pie chart.<br />
data-charttype none Type of the chart (bar, pie, groupbar, or line).<br />
data-color none Color of the chart as hex triplet, for example #FFFFFF for<br />
white, or as standard HTML names, for example blue or<br />
black.<br />
data-dimension-line none Attribute whose distinct value count is to be displayed in<br />
grouped bar or line chart.<br />
data-dimension-x none Attribute that is displayed as additional dimension inside the<br />
chart as group of bars or different lines.<br />
data-dimension-y none Measurement that is displayed on the y-axis. In a search<br />
scenario, the only measurement available is the distinct value<br />
count ($count) of the attribute defined in data-<br />
dataaggregationsortorde<br />
r<br />
dimension-line.<br />
ASC Descending (DESC) or ascending order for sorting the counts<br />
in the charts. Here you can override the sort order defined<br />
centrally in the workarea widget.<br />
data-topsmall none Defines how many bars or pie segments are displayed when the<br />
chart is small.<br />
dataanimationduration<br />
Related Links<br />
Connecting Your Source Data [page 314]<br />
inaresultlist<br />
1000 Duration of the animation, in milliseconds, when a chart adapts<br />
(default 1000). 0 means that animation is switched off.<br />
Parameter Name Default Value Description<br />
data-maxresultslarge 10 Maximum number of result items displayed on one<br />
page if the list is enlarged in the content pane.<br />
data-maxresultssmall 5 Maximum number of result items displayed on one<br />
page if the list is small in the facet column.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 317
Parameter Name Default Value Description<br />
data-responseattributes none Attributes to be displayed in a result list entry. The<br />
actual scope and layout of the response attributes on<br />
the result list and details pane are defined in the files<br />
referenced in the data-resulttemplate<br />
parameters.<br />
Note:<br />
Do not leave the dataresponseattributes<br />
parameter empty.<br />
Only use attributes from the main table of the<br />
view or attributes that are joined in 1:1 from<br />
other tables.<br />
Attributes with data type blob are not<br />
supported by the HTTP service.<br />
data-detailwidth 600 Width of the details pop-up in pixels.<br />
data-detailheight 800 Height of the details pop-up in pixels.<br />
data-resulttemplate none Reference to HTML and CSS files defining the layouts<br />
data-resulttemplate-css none<br />
of the result lists (small and large) and of the details<br />
pop-up.<br />
data-resulttemplate-small none<br />
data-resulttemplatesmall-css<br />
data-resulttemplatedetail<br />
data-resulttemplatedetail-css<br />
none<br />
none<br />
none<br />
data-scoresortorder DESC By default, the result list is sorted according to the<br />
ranking by relevancy for the search term(s). Leave the<br />
default sort order unchanged.<br />
data-orderby none Attribute by whose values the list is sorted<br />
alphabetically. First choice for sorting is always the<br />
ranking by relevancy for the search term(s). The<br />
data-orderby setting only steps in if there is no<br />
relevancy ranking available, for example before the<br />
first search, or if there are equal ranking values.<br />
data-sortorder ASC Ascending or descending (DESC) order for the dataorderby<br />
parameter.<br />
Related Links<br />
Connecting Your Source Data [page 314]<br />
Defining the Layout of Result Lists and Details [page 319]<br />
318<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search
11.3.9 Defining the Layout of Result Lists and Details<br />
You can select which attributes are displayed and how they are displayed in the result lists (small or centered) and<br />
on the details pop-up. In the search HTML file, the result templates are referenced in the inaresultlist<br />
widget using the data-resulttemplate parameters.<br />
The templates folder contains the HTML and CSS templates of the demo app for adapting. You can create your<br />
own result layouts from the templates and reference them in the parameters. Make sure that the path is correct.<br />
In the HTML templates, you define what is in a result entry in the different views. You can enter fixed text and<br />
reference the response properties and values in double braces.<br />
For a deeper understanding of these HTML templates, familiarize yourself with the Tempo JSON rendering<br />
engine.<br />
Note: If you want to integrate graphics in result list templates, define the exact width and height in pixels.<br />
Use the corresponding CSS files to define the result layouts and the behavior on hover events. To tweak the layout<br />
of the details screen further, you can also use the widgets provided by jQuery UI.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Enabling Search<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 319
12 Setting Up Roles and<br />
Authorizations<br />
12.1 The Authorization Model<br />
Authorization mechanisms ensure that authenticated users can do only those things they are allowed to do. You<br />
can use the authorization mechanisms of the <strong>SAP</strong> <strong>HANA</strong> database to specify who is allowed to access which data<br />
and for which activities.<br />
Authorization mechanisms can also be used to help control who is allowed to execute stored procedures and<br />
functions or execute system-level activities, for example: making backups, creating schema, users, roles, and so<br />
on.<br />
Authorizations are specified by granting privileges to principals. Principals are either users or roles. Roles<br />
represent collections of privileges that can be granted to users or other roles, which enables you to create a<br />
hierarchy of roles. Privileges are granted to principals by users.<br />
<strong>SAP</strong> <strong>HANA</strong> database authorization mechanisms use the following privileges:<br />
● System privileges<br />
Perform system-level operations or administrative tasks<br />
● Object privileges<br />
Perform specified actions on specified database objects<br />
● Analytic privileges<br />
Allow selective access control for database views generated when modeled are activated<br />
● Package Privileges<br />
Allow operations on packages, for example, creation and maintenance. Privileges can differ for native and<br />
imported packages.<br />
Other types of privileges enable you to provide specific additional authorizations, for example, to users who need<br />
to perform administrative tasks on objects in the repository or to users and clients that need access to<br />
applications:<br />
● Repository Privileges<br />
Enable users to perform basic repository operations, for example: import and export packages, and maintain<br />
delivery units (DU)<br />
● Application Privileges<br />
320<br />
Enable users and clients to access an application, configure what data to expose, and set rules for exposing<br />
URLs.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
12.2 Authentication Overview<br />
Authentication is the process used to validate the identity of the users who connect to <strong>SAP</strong> <strong>HANA</strong>.<br />
Secure authentication mechanisms ensure that the users requesting a connection really are who they claim to be.<br />
Note: For connections to <strong>SAP</strong> <strong>HANA</strong> it is important to distinguish between SQL- and HTTP-based<br />
connections.<br />
For SQL access to <strong>SAP</strong> <strong>HANA</strong> by means of client interfaces, for example, JDBC or ODBC, the following<br />
authentication methods are supported:<br />
● External authentication:<br />
○ Kerberos services<br />
A standardized service for client authentication in networks. The client connects to the Kerberos server to<br />
authenticate the user and to acquire an authentication ticket that proves the user’s identity to the <strong>SAP</strong><br />
<strong>HANA</strong> database. The client uses the ticket to connect to the <strong>SAP</strong> <strong>HANA</strong> database. Kerberos also ensures<br />
the correct identity of the server.<br />
○ SAML (bearer token)<br />
<strong>SAP</strong> <strong>HANA</strong> can authenticate users who provide a valid standard-based SAML assertion issued by a<br />
trusted identity provider.<br />
● Internal authentication<br />
Users are authenticated by the <strong>SAP</strong> <strong>HANA</strong> database using the database user name and password.<br />
<strong>SAP</strong> <strong>HANA</strong> maps the external identity approved by external authentication service to the identity of an internal<br />
database user. This internal database user is then used for authorization checks during the database session.<br />
For HTTP access to <strong>SAP</strong> <strong>HANA</strong> by means of <strong>SAP</strong> <strong>HANA</strong> XS, the following authentication methods are supported:<br />
● User name and password:<br />
○ Using HTTP basic authentication<br />
○ Form-based authentication<br />
● <strong>SAP</strong> logon tickets<br />
12.3 Roles<br />
Roles contain privileges that are used to define which data, application, or function can be accessed and in which<br />
manner consumed. Roles are assigned either to users or to other roles at runtime.<br />
<strong>SAP</strong> delivers some generic roles with <strong>SAP</strong> <strong>HANA</strong> that can be used as they are or as templates (during design time)<br />
for creating roles that meet your company's specific requirements. More information about roles, their use at<br />
runtime and in design time are explained in the subsequent sections.<br />
● Roles<br />
● Roles as Repository Objects<br />
● Creating Roles in the Repository<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 321
12.3.1 Roles<br />
A role is a collection of privileges that can be granted to either a user or another role in runtime.<br />
A role typically contains the privileges required for a particular function or task, for example:<br />
● Business end users reading reports using client tools such as Microsoft Excel<br />
● Modelers creating models and reports in the modeler of the <strong>SAP</strong> <strong>HANA</strong> studio<br />
● Database administrators operating and maintaining the database and users in the Administration editor of the<br />
<strong>SAP</strong> <strong>HANA</strong> studio<br />
Privileges can be granted directly to users of the <strong>SAP</strong> <strong>HANA</strong> database. However, roles are the standard<br />
mechanism of granting privileges as they allow you to implement complex, reusable hierarchies of user access<br />
that can be modeled on business roles. Several standard roles are delivered with the <strong>SAP</strong> <strong>HANA</strong> database (for<br />
example, MODELING, MONITORING). You can use these as templates for creating your own roles.<br />
Roles in the <strong>SAP</strong> <strong>HANA</strong> database can exist as runtime objects only, or as design-time objects that become<br />
runtime objects on activation.<br />
Role Structure<br />
A role can contain any number of the following privileges:<br />
● System privileges for administrative tasks (for example, AUDIT ADMIN, BACKUP ADMIN, CATALOG READ)<br />
● Object privileges on database objects (for example, SELECT, INSERT, UPDATE)<br />
● Package privileges on repository packages (for example, REPO.READ, REPO.EDIT_NATIVE_OBJECTS,<br />
REPO.ACTIVATE_NATIVE_OBJECTS)<br />
● Analytic privileges on <strong>SAP</strong> <strong>HANA</strong> information models<br />
● Application privileges for enabling access to <strong>SAP</strong> <strong>HANA</strong> XS applications<br />
Note: Application privileges cannot be granted to roles in the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
A role can also extend other roles.<br />
Role Modeling<br />
You can model roles in the following ways:<br />
● As runtime objects on the basis of SQL statements<br />
● As design-time objects in the repository of the <strong>SAP</strong> <strong>HANA</strong> database<br />
It is recommended that you model roles as design-time objects for the following reasons.<br />
Firstly, unlike roles created in runtime, roles created as design-time objects can be transported between systems.<br />
This is important for application development as it means that developers can model roles as part of their<br />
application's security concept and then ship these roles or role templates with the application. Being able to<br />
transport roles is also advantageous for modelers implementing complex access control on analytic content. They<br />
can model roles in a test system and then transport them into a productive system. This avoids unnecessary<br />
duplication of effort.<br />
322<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Secondly, roles created as design-time objects are not directly associated with a database user. They are created<br />
by the technical user _SYS_REPO and granted through the execution of stored procedures. Any user with access<br />
to these procedures can grant and revoke a role. Roles created in runtime are granted directly by the database<br />
user and can only be revoked by the same user. Additionally, if the database user is deleted, all roles that he or she<br />
granted are revoked. As database users correspond to real people, this could impact the implementation of your<br />
authorization concept, for example, if an employee leaves the organization or is on vacation.<br />
Caution: The design-time version of a role in the repository and its activated runtime version should<br />
always contain the same privileges. In particular, additional privileges should not be granted to the<br />
activated runtime version of a role created in the repository. Although there is no mechanism of<br />
preventing a user from doing this, the next time the role is activated in the repository, any changes made<br />
to the role in runtime will be reverted. It is therefore important that the activated runtime version of a role<br />
is not changed in runtime.<br />
12.3.2 Roles as Repository Objects<br />
The repository of the <strong>SAP</strong> <strong>HANA</strong> database consists of packages that contain design-time versions of various<br />
objects. Being a repository object has several implications for a role.<br />
Grantable Privileges<br />
According to the authorization concept of the <strong>SAP</strong> <strong>HANA</strong> database, a user can only grant a privilege to a user<br />
directly or indirectly in a role if the following prerequisites are met:<br />
● The user has the privilege him- or herself<br />
● The user is authorized to grant the privilege to others (WITH ADMIN OPTION or WITH GRANT OPTION)<br />
A user is also authorized to grant SQL object privileges on objects that he or she owns.<br />
The technical user _SYS_REPO is the owner of all objects in the repository, as well as the runtime objects that are<br />
created on activation. This means that when you create a role as a repository object, you can grant the following<br />
privileges:<br />
● Privileges that have been granted to the technical user _SYS_REPO and that _SYS_REPO can grant further.<br />
This is automatically the case for system privileges, package privileges, analytic privileges, and application<br />
privileges. Therefore, all system privileges, package privileges, analytic privileges, and application privileges<br />
can always be granted in modeled roles.<br />
● Privileges on objects that _SYS_REPO owns.<br />
_SYS_REPO owns all activated objects. Object privileges on non-activated runtime objects must be explicitly<br />
granted to _SYS_REPO. It is recommended that you use a technical user to do this to ensure that privileges<br />
are not dropped when the granting user is dropped (for example, because she leaves the company.<br />
The following table summarizes the situation described above:<br />
Privilege Action Necessary to Grant in Repository Role<br />
System privilege None<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 323
Privilege Action Necessary to Grant in Repository Role<br />
Package privilege None<br />
Analytic privilege None<br />
Application privilege None<br />
SQL object on activated object (for example, attribute<br />
view, analytic view)<br />
SQL object privilege on runtime object (for example,<br />
replicated table)<br />
Granting and Revoking<br />
None<br />
Grant privilege to user _SYS_REPO with WITH GRANT<br />
OPTION<br />
It is not possible to grant and revoke activated design-time roles using the GRANT and REVOKE SQL statements.<br />
Instead, roles are granted and revoked through the execution of the procedures GRANT_ACTIVATED_ROLE and<br />
REVOKE_ACTIVATED_ROLE. Therefore, to be able to grant or revoke a role, a user must have the SQL object<br />
privilege EXECUTE on these procedures.<br />
WITH ADMIN OPTION and WITH GRANT OPTION<br />
When you create a role on the basis of SQL statements (that is, as a runtime object), you can grant privileges with<br />
the additional parameters WITH ADMIN OPTION or WITH GRANT OPTION. This allows a user who is granted the<br />
role to grant the privileges contained within the role to other users and roles. However, if you are implementing<br />
your authorization concept with privileges encapsulated within roles created in design time, then you do not want<br />
users to grant privileges using SQL statements. Therefore, it is not possible to pass the parameters WITH ADMIN<br />
OPTION or WITH GRANT OPTION with privileges when you model roles as repository objects.<br />
Similarly, when you grant an activated role to a user, it is not possible to allow the user to grant the role further<br />
(WITH ADMIN OPTION is not available).<br />
Auditability<br />
The auditing feature of the <strong>SAP</strong> <strong>HANA</strong> database allows you to monitor and record selected actions performed in<br />
your database system. One action that is typically audited is changes to user authorization. If you are using roles<br />
created in the repository to grant privileges to users, then it is important to note that the creation of runtime roles<br />
through activation cannot be meaningfully audited.<br />
12.3.3 Creating Roles in the Repository<br />
You model roles in the <strong>SAP</strong> <strong>HANA</strong> repository in a domain-specific language (DSL).<br />
● A shared project must exist with a suitable package for storing roles.<br />
● You have the package and system privileges required for modeling and activating objects in the repository.<br />
324<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Caution: Theoretically, a user with authorization to model and activate repository objects can change<br />
a role that he has been granted. Once the role is activated, the user has the new privileges that he or<br />
she just added. Therefore, it is important that roles in productive systems are imported from a test or<br />
development system and changes to imported objects are not allowed. This danger is however not<br />
specific to roles but also applies to other repository objects, for example, modeled views.<br />
● You have granted privileges on non-activated runtime objects that you want to grant in the new role to the<br />
technical user _SYS_REPO.<br />
The following general conventions apply when modeling a role definition using the role DSL:<br />
● Comments start with a double-slash (//) or double-dash (--) and run to the end of the line.<br />
● When specifying a reference to a design-time object, you must always specify the package name as follows:<br />
○ package::object if you are referencing a design-time role<br />
○ package:object.extension if you are referencing any other design-time object<br />
● When specifying multiple privileges on the same object or the same privilege on multiple objects, you can do<br />
so individually line by line, or you can group them on a single line. Separate multiple objects and/or multiple<br />
privileges using a comma.<br />
1. From the main menu in the <strong>SAP</strong> <strong>HANA</strong> studio, choose File New Other <strong>SAP</strong> <strong>HANA</strong> Repository Role<br />
.<br />
The New Role dialog box appears.<br />
2. In the Container field, enter the path to the package where you want to create the role.<br />
3. In the Role name field, enter the name of the new role.<br />
4. Choose Finish.<br />
The new role appears in the Project Explorer view and opens in the role editor as follows:<br />
// an empty role<br />
role :: {<br />
}<br />
The role is now ready to be defined.<br />
5. Optional: Specify the role(s) that you want to embed within the new role.<br />
You can specify both roles created in runtime and repository roles as follows:<br />
○ extends role ::<br />
○ extends catalog role "role_name"<br />
Example:<br />
role ::<br />
extends role sap.example::role1<br />
extends catalog role "CATROLE2"<br />
{<br />
}<br />
6. Model the required privileges.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 325
326<br />
Note: Unlike when you create a role using SQL statements, it is not possible to grant ALL<br />
PRIVILEGES when creating a role in the repository. You must model every privilege individually.<br />
a) Model system privileges using the keyword "system privilege" as follows: system privilege:<br />
PRIVILEGE;<br />
Example:<br />
role ::<br />
{<br />
// multiple privileges in one line are OK<br />
system privilege: BACKUP ADMIN, USER ADMIN;<br />
}<br />
// you can also split lists into multiple entries<br />
system privilege: LICENSE ADMIN;<br />
b) Optional: Model object privileges on the design-time objects views and procedures using the keyword<br />
"SQL object" as follows: sql object :.extension: PRIVILEGE;<br />
Example:<br />
role ::<br />
{<br />
sql object sap.example:MY_VIEW.attributeview: DROP;<br />
// object privileges can be split across lines<br />
sql object sap.example:MY_VIEW.attributeview: DROP;<br />
// a single privilege can be given on multiple objects in a<br />
single line<br />
sql object sap.example:MY_VIEW.attributeview,<br />
sap.example:MY_OTHER_VIEW.analyticview,<br />
sap.example:MY_THIRD_VIEW.analyticview: SELECT;<br />
}<br />
c) Optional: Model object privileges on catalog objects using the keyword "catalog SQL object" as follows:<br />
catalog sql object "SCHEMA"."CATALOG_OBJECT": PRIVILEGE;<br />
Example:<br />
Note: You must always qualify catalog objects with the schema name. You must also reference<br />
catalog objects within double quotes, unlike design-time objects.<br />
role ::<br />
{<br />
// catalog objects must always be qualified with the schema name<br />
catalog sql object "MY_SCHEMA"."MY_VIEW": SELECT;<br />
}<br />
d) Optional: Model schema privileges on schemas using the keywords "catalog schema" or "schema" as<br />
follows depending on whether you are referring to an activated schema or a schema in the repository:<br />
○ catalog schema "SCHEMA": PRIVILEGE;<br />
○ schema :.schema: PRIVILEGE;<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Example:<br />
role ::<br />
{<br />
catalog schema "MY_SCHEMA": SELECT;<br />
schema sap.example:MY_OTHER_SCHEMA.schema: SELECT;<br />
}<br />
e) Optional: Model package privileges using the keywords "package" as follows: package PACKAGE:<br />
PRIVILEGE;<br />
Example:<br />
role ::<br />
{<br />
package sap.example: REPO.READ;<br />
}<br />
f) Optional: Model analytic privileges using the keywords "analytic privilege" or "catalog analytic privilege"<br />
depending on whether you are referring to an activated analytic privilege or a runtime analytic privilege<br />
○ analytic privilege: :.analyticprivilege<br />
○ catalog analytic privilege: "analytic_priv_name";<br />
Example:<br />
role ::<br />
{<br />
analytic privilege: sap.example:sp1.analyticprivilege,<br />
sap.example:AP2.analyticprivilege;<br />
catalog analytic privilege: "sp3";<br />
}<br />
g) Optional: Model application privileges using the keyword "application privilege" as follows:<br />
application privilege: ;<br />
Example:<br />
role ::<br />
{<br />
application privilege: sap.example::Execute;<br />
}<br />
Note: Application privileges are implemented using the application-privileges file<br />
(.xsprivileges).<br />
7. From the main menu, choose File Save .<br />
The role is saved as an .hdbrole file. After it has been saved, the file is committed to the repository<br />
8. Activate the role by right-clicking it in the Project Explorer view and choosing Team Activate .<br />
Note: Any changes made to a previously activated version of the role in runtime will be reverted on<br />
activation. This is to ensure that the design-time version of a role in the repository and its activated<br />
runtime version contain the same privileges. It is therefore important that the activated runtime<br />
version of a role is not changed in runtime.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 327
The activated role is now visible in the Navigator view under Security Roles following the naming convention<br />
package::role_name and can be granted to users as part of user provisioning.<br />
Complete Role Definition Example<br />
role ::<br />
extends role sap.example::role1<br />
extends catalog role "CATROLE1", "CATROLE2"<br />
{<br />
// system privileges<br />
system privilege: BACKUP ADMIN, USER ADMIN;<br />
// schema privileges<br />
catalog schema "SYSTEM": SELECT;<br />
schema sap.example:app1.schema: INSERT, UPDATE, DELETE;<br />
// sql object privileges<br />
// privileges on the same object may be split up in several lines<br />
catalog sql object "SYSTEM"."TABLE2": SELECT;<br />
catalog sql object "SYSTEM"."TABLE2": INSERT, UPDATE, DELETE;<br />
// or a list of objects may get a list of privileges (object =<br />
table, view, procedure, sequence)<br />
// SELECT, DROP for all objects in list<br />
sql object sap.example:VIEW1.attributeview,<br />
sap.example:PROC1.procedure, sap.example:SEQ1.sequence: SELECT, DROP;<br />
// additional INSERT, UPDATE for TABLE1<br />
sql object sap.example:MY_VIEW.attributeview: DROP;<br />
// analytic privileges<br />
analytic privilege: sap.example:sp1.analyticprivilege,<br />
sap.example:AP2.analyticprivilege;<br />
catalog analytic privilege: "sp3";<br />
}<br />
Related Links<br />
// design time privileges<br />
package sap.example: REPO.EDIT_NATIVE_OBJECTS;<br />
package sap.example, sap.co: REPO.READ;<br />
application privilege: sap.example::Execute, sap.example::Save;<br />
Setting Up Your Application [page 34]<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the design-time artifacts that make up your<br />
application are stored in the repository like files in a file system. You first choose a root folder for your<br />
application-development activities, and within this folder you create additional subfolders to organize the<br />
applications and the application content according to your own requirements.<br />
The Application-Privileges File [page 59]<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the application-privileges (.xssprivileges)<br />
file can be used to create or define the authorization privileges required for access to an <strong>SAP</strong> <strong>HANA</strong> XS<br />
application, for example, to start the application or to perform administrative actions on an application. These<br />
privileges can be checked by an application at runtime.<br />
<strong>SAP</strong> <strong>HANA</strong> Administration <strong>Guide</strong><br />
328<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
12.4 Privileges<br />
<strong>SAP</strong> <strong>HANA</strong> offers various privileges that can be assigned to users. Users can be a system, an application, a<br />
service, or a person, and each user is assigned specific roles. Privileges can be assigned to users, roles, or both.<br />
There are several privileges that are required either by the <strong>SAP</strong> <strong>HANA</strong> studio or by development tools, such as<br />
SQL. The following types of privileges are explained in the subsequent sections.<br />
● System privileges<br />
● Object privileges<br />
● Package privileges<br />
● Analytic privileges<br />
This section also contains information for creating and granting privileges to users.<br />
12.4.1 System Privileges<br />
System privileges are required to perform system-level operations or administrative tasks.<br />
The following lists shows some of the most common system-level tasks that administrators regularly must<br />
perform:<br />
● Database schema<br />
Creation and deletion of database schema<br />
● Users/Roles<br />
Maintenance and management of users and roles<br />
● Monitor/Trace<br />
Administration of monitoring and tracing<br />
● Backup/Restore<br />
Performance of backup and restore operations<br />
In the <strong>SAP</strong> <strong>HANA</strong> database the user SYSTEM has all system privileges. The SYSTEM user can grant system<br />
privileges to other users and roles.<br />
12.4.2 Object Privileges<br />
Object privileges enable users to perform specified actions on specified database objects.<br />
Object privileges are not specific to the <strong>SAP</strong> <strong>HANA</strong> database; they are part of the SQL standard. You can use the<br />
SQL statements GRANT and REVOKE to manage privileges.<br />
Note: . If object privileges (or any other privilege type) are granted to roles created in the repository,<br />
granting and revoking actions happen through the execution of stored procedures.<br />
The set of actions that can be allowed by an object privilege depends on the object type. For tables, you can use<br />
actions such as: drop, alter, select, insert and update. An execute action is available for privileges for procedures<br />
and functions. Privileges on a schema level are used to enable actions such as: create objects, perform select,<br />
update, delete or execute operations on all objects contained in the schema.<br />
In the <strong>SAP</strong> <strong>HANA</strong> database object privileges are not only available for database catalog objects such as tables,<br />
views and procedures. Object privileges can also be granted for non-catalog objects such as development objects<br />
in the repository of the <strong>SAP</strong> <strong>HANA</strong> database.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 329
Some database objects depend on other objects. Views, for example, are defined as queries on other tables and<br />
views. The authorization for an operation on the dependent object (the queried tables and views) requires<br />
privileges for the dependent object and the underlying object. In case of views, the <strong>SAP</strong> <strong>HANA</strong> database<br />
implements the standard SQL behavior. A user has the authorization for an operation on a view if the following is<br />
true:<br />
● The privilege for operations on the view has been granted to the user or a role assigned to the user.<br />
● The owner of the view has the corresponding privileges on the underlying objects with the option to grant<br />
them to others.<br />
This behavior can be used to grant selective access to a table.<br />
12.4.3 Package Privileges<br />
In the <strong>SAP</strong> <strong>HANA</strong> repository, authorizations can be assigned to individual packages.<br />
Authorizations assigned to a repository package are implicitly assigned to the design-time objects in the package<br />
as well as to all sub-packages. Users are only allowed to maintain objects in a repository package if they have the<br />
necessary privileges for the package in which they want to perform an operation, for example to read or write to<br />
an object in that package.<br />
Note: Package authorizations can be set for a specific user or for a role.<br />
If the user-authorization check establishes that a user does not have the necessary privileges to perform the<br />
requested operation in a specific package, the authorization check is repeated on the parent package and<br />
recursively up the package hierarchy to the root level of the repository. If the user does not have the necessary<br />
privileges for any of the packages in the hierarchy chain, the authorization check fails and the user is not<br />
permitted to perform the requested operation.<br />
In the context of repository authorizations, there is a distinction to be made between native packages and<br />
imported packages.<br />
● Native Package<br />
A package that is created in the current system and expected to be edited in the current system. Changes to<br />
package objects must be performed in the original development system where they were created and<br />
transported into subsequent systems. The content of native packages are regularly edited by developers.<br />
● Imported Package<br />
A package that is created in a remote system and imported into the current system. Imported packages<br />
should not usually be modified, except when replaced by new imports during an update. Otherwise, imported<br />
packages should only be modified in exceptional cases, for example, to carry out emergency repairs.<br />
To perform every-day, package-related, application-development tasks in the repository, developers typically<br />
need the following privileges for the application packages:<br />
● REPO.READ<br />
Read access to the selected package and design-time objects (both native and imported)<br />
● REPO.EDIT_NATIVE_OBJECTS<br />
Authorization to modify design-time objects in packages originating in the system the user is working in<br />
● REPO.ACTIVATE_NATIVE_OBJECTS<br />
Authorization to activate/reactivate design-time objects in packages originating in the system the user is<br />
working in<br />
● REPO.MAINTAIN_NATIVE_PACKAGES<br />
330<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Authorization to update or delete native packages, or create sub-packages of packages originating in the<br />
system in which the user is working<br />
<strong>SAP</strong> <strong>HANA</strong> Repository Privileges<br />
In addition to the authorizations you can grant users for specific packages (and the design-time objects in those<br />
packages), you can also assign general system privileges to users to enable them to perform basic repository<br />
operations, for example: importing and exporting content, and maintaining delivery units (DU).<br />
If your daily tasks include general administration tasks, you need basic system-level privileges in the repository.<br />
To perform basic administration tasks in the repository, you typically need the following privileges:<br />
● REPO.EXPORT<br />
Enables you to export delivery units; exporting a DU transports it to another system<br />
● REPO.IMPORT<br />
Enables you to import delivery units; importing a DU transports it from another system<br />
● REPO.MAINTAIN_DELIVERY_UNITS<br />
Enables you to maintain your own delivery units (the DU-vendor must equal the system-vendor)<br />
● REPO.WORK_IN_FOREIGN_WORKSPACE<br />
Enables you to move objects from a "foreign" inactive workspace into your own workspace<br />
You can grant or revoke basic, repository privileges to users in the following ways:<br />
● <strong>SAP</strong> <strong>HANA</strong> Studio<br />
The System Privileges tab page in the Modeler perspective: Catalog -> Authorization -> Roles or Users<br />
Note: If you want to access the repository from the <strong>SAP</strong> <strong>HANA</strong> studio, Eclipse, or other clients,you need<br />
the EXECUTE privilege for SYS.REPOSITORY_REST, the database procedure through which the REST<br />
API is tunneled.<br />
Defining Repository Package Privileges<br />
In the <strong>SAP</strong> <strong>HANA</strong> repository, you can set package authorizations for a specific user or for a role. Authorizations<br />
that are assigned to a repository package are implicitly assigned to all sub-packages, too. You can also specify if<br />
the assigned user authorizations can be passed on to other users.<br />
To set user (or role) authorizations for repository packages, perform the following steps:<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, open the Navigator view of the Modeler perspective.<br />
2. In the Navigator view, expand the Security Roles/Users node for the system hosting the repository that<br />
contains the packages you want to grant access to.<br />
You can also define roles via source files; roles defined in this way can be assigned to a delivery unit and<br />
transported to other systems.<br />
3. Double click the user (or role) to whom you want to assign authorizations.<br />
4. Open the Package Privileges tab page.<br />
5. Choose [+] to add one or more packages. Press and hold the Ctrl key to select multiple packages.<br />
6. In the Select Repository Package dialog, use all or part of the package name to locate the repository package<br />
that you want to authorize access to.<br />
7. Select one or more repository packages that you want to authorize access to; the selected packages appear<br />
in the Package Privileges tab page.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 331
8. Select the packages to which you want authorize access and, in the Privileges for screen page, check the<br />
required privileges, for example:<br />
a) REPO.READ<br />
Read access to the selected package and design-time objects (both native and imported)<br />
b) REPO.EDIT_NATIVE_OBJECTS<br />
Authorization to modify design-time objects in packages originating in the system the user is working in<br />
c) REPO.ACTIVATE_NATIVE_OBJECTS<br />
Authorization to activate/reactivate design-time objects in packages originating in the system the user is<br />
working in<br />
d) REPO.MAINTAIN_NATIVE_PACKAGES<br />
Authorization to update or delete native packages, or create sub-packages of packages originating in the<br />
system in which the user is working<br />
12.4.4 Analytic Privileges<br />
SQL privileges impose coarse-grained restrictions at object level only. Users either have access to an object, such<br />
as a table, view or procedure, or they do not. While this is often sufficient, there are cases when access to data in<br />
an object depends on certain values or combinations of values. Analytic privileges are used in the <strong>SAP</strong> <strong>HANA</strong><br />
database to provide such fine-grained control of which data individual users can see within the same view.<br />
Note: Sales data for all regions are contained within one analytic view. However, regional sales managers<br />
should only see the data for their region. In this case, an analytic privilege could be modeled so that they<br />
can all query the view, but only the data that each user is authorized to see is returned.<br />
Analytic privileges are intended to control access to <strong>SAP</strong> <strong>HANA</strong> information models, that is:<br />
● Attribute views<br />
● Analytic views<br />
● Calculation views<br />
Therefore, all column views modeled and activated in the <strong>SAP</strong> <strong>HANA</strong> modeler automatically enforce an<br />
authorization check based on analytic privileges. Column views created using SQL must be explicitly registered<br />
for such a check (by passing the parameter REGISTERVIEWFORAPCHECK).<br />
Note: Analytic privileges do not apply to database tables or views modeled on row-store tables. Access to<br />
database tables and row views is controlled entirely by SQL object privileges.<br />
You create and manage analytic privileges in the <strong>SAP</strong> <strong>HANA</strong> modeler.<br />
Note: Some advanced features of analytic privileges, namely dynamic value filters, can only be<br />
implemented using SQL. The management of such analytic privileges created in SQL also varies to those<br />
created in the <strong>SAP</strong> <strong>HANA</strong> modeler.<br />
Structure of Analytic Privileges<br />
An analytic privilege consists of a set of restrictions against which user access to a particular attribute view,<br />
analytic view, or calculation view is verified. Each restriction controls the authorization check on the restricted<br />
view using a set of value filters. A value filter defines a check condition that verifies whether or not the values of<br />
the view (or view columns) qualify for user access.<br />
The specification of these restrictions is contained in an XML document that conforms to a defined XML schema<br />
definition (XSD).<br />
The following restriction types can be used to restrict data access:<br />
● View<br />
332<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
● Activity<br />
● Validity<br />
● Attribute<br />
The following operators can be used to define value filters in the restrictions.<br />
Note: The activity and validity restrictions support only a subset of these operators.<br />
● IN <br />
● CP <br />
● EQ (=), LE (=) <br />
● BT <br />
● IS_NULL<br />
● NOT_NULL<br />
All of the above operators, except IS_NULL and NOT_NULL, accept empty strings (“”) as filter operands.<br />
The following are examples of how empty strings can be used with the filter operators:<br />
● For the IN operator: IN (“”, “A”, “B”) to filter on these exact values<br />
● As a lower limit in comparison operators, such as:<br />
○ BT (“”, “XYZ”), which is equivalent to NOT_NULL AND LE “XYZ”<br />
○ GT “”, which is equivalent to NOT_NULL<br />
○ LE “”, which is equivalent to EQ “”<br />
○ LT “”, which will always return false<br />
○ CP “”, which is equivalent to EQ “”<br />
The filter conditions CP “*” will also return rows with empty-string as values in the corresponding attribute.<br />
View Restriction<br />
This restriction specifies to which column view(s) the analytic privilege applies. It can be a single view, a list of<br />
views, or all views. An analytic privilege must have exactly one cube restriction.<br />
Example: IN ("Cube1", "Cube2")<br />
Note: When an analytic view is created in the <strong>SAP</strong> <strong>HANA</strong> modeler, automatically-generated views are<br />
included automatically in the cube restriction.<br />
Activity Restriction<br />
This restriction specifies the activities that the user is allowed to perform on the restricted view(s), for example,<br />
read data. An analytic privilege must have exactly one activity restriction.<br />
Example: EQ "read", or EQ "edit"<br />
Note: Currently, all analytic privileges created in the <strong>SAP</strong> <strong>HANA</strong> modeler are automatically configured to<br />
restrict access to READ activity only. This corresponds to SQL SELECT queries. This is due to the fact that<br />
the attribute, analytic, and calculation views are read-only views. This restriction is therefore not<br />
configurable.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 333
Validity Restriction<br />
This restriction specifies the validity period of the analytic privilege. An analytic privilege must have exactly one<br />
validity restriction.<br />
Example: GT 2010/10/01, 01:01:00.000<br />
Note: All analytic privileges automatically become immediately valid and have unlimited validity when<br />
activated in the <strong>SAP</strong> <strong>HANA</strong> modeler. This restriction is therefore not configurable.<br />
Attribute Restriction<br />
This restriction specifies the value range that the user is permitted to access. Attribute restrictions are applied to<br />
the actual attributes of a view. Each attribute restriction is relevant for one dimension attribute, which can contain<br />
multiple value filters. Each value filter represents a logical filter condition.<br />
Value filters for attribute restrictions can be static or dynamic.<br />
● A static value filter consists of an operator and either a list of values as the filter operands or a single value as<br />
the filter operand. All data types are supported except those for LOB data types (CLOB, BLOB, and NCLOB).<br />
For example, a value filter (EQ 2006) can be defined for an attribute YEAR in a dimension restriction to filter<br />
accessible data using the condition YEAR=2006 for potential users.<br />
Note: Only attributes, not aggregatable facts (for example, measures or key figures) can be used in<br />
dimension restrictions for analytic views.<br />
● A dynamic value filter consists of an operator and a stored procedure call that determines the operand value<br />
at runtime.<br />
For example, a value filter (IN (GET_MATERIAL_NUMBER_FOR_CURRENT_USER())) is defined for the<br />
attribute MATERIAL_NUMBER. This filter indicates that a user with this analytic privilege is only allowed to<br />
access material data with the numbers returned by the procedure<br />
GET_MATERIAL_NUMBER_FOR_CURRENT_USER.<br />
Note: If you create an analytic privilege in the <strong>SAP</strong> <strong>HANA</strong> modeler, it is not possible to specify a<br />
procedure call when defining restrictions. If you want to create analytic privileges with dynamic filter<br />
conditions, you must do so using SQL.<br />
It is possible to combine static and dynamic value filters.<br />
An analytic privilege can have multiple attribute restrictions, but it must have at least one attribute restriction. An<br />
attribute restriction must have at least one value filter. Therefore, if you want to permit access to the whole<br />
content of a restricted view, then the attribute restriction must specify all attributes.<br />
Similarly, if you want to permit access to the whole content of the view with the corresponding attribute, then the<br />
value filter must specify all values.<br />
334<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
The <strong>SAP</strong> <strong>HANA</strong> modeler automatically implements this specification if you do not select either an attribute<br />
restriction or a value filter. However, if you create the analytic privilege using SQL, you must make the<br />
specification manually.<br />
Example 1:<br />
<br />
<br />
<br />
Example 2:<br />
<br />
<br />
<br />
<br />
<br />
Logical Combination of Restrictions and Filter Conditions<br />
The result of user queries on restricted views is filtered according to the conditions specified by the analytic<br />
privileges granted to the user as follows:<br />
● Multiple analytic privileges are combined with the logical operator OR.<br />
● Within one analytic privilege, all attribute restrictions are combined with the logical operator AND.<br />
● Within one attribute restriction, all value filters on the attribute are combined with the logical operator OR.<br />
You create two analytic privileges AP1 and AP2. AP1 has the following attribute restrictions:<br />
● Restriction R11 restricting the attribute Year with the value filters (EQ 2006) and (BT 2008,<br />
2010)<br />
● Restriction R12 restricting the attribute Country with the value filter (IN ("USA", "Germany"))<br />
Given that multiple value filters are combined with the logical operator OR and multiple attribute<br />
restrictions are combined with the logical operator AND, AP1 generates the condition:<br />
((Year = 2006) OR (Year BT 2008 and 2010)) AND (Country IN ("USA",<br />
"Germany"))<br />
AP2 has the following restriction:<br />
Restriction R21 restricting the attribute Country with the value filter (EQ "France")<br />
AP2 generates the condition:<br />
(Country = "France")<br />
Any query of a user who has been granted both AP1 and AP2 will therefore be appended with the following<br />
WHERE clause:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 335
((Year = 2006) OR (Year BT 2008 and 2010)) AND (Country IN ("USA",<br />
"Germany"))) OR (Country = "France")<br />
Dynamic Value Filters in the Attribute Restriction of Analytic Privileges<br />
The attribute restriction of an analytic privilege specifies the value range that the user is permitted to access using<br />
value filters. In addition to static scalar values, stored procedures can be used to define filters. This allows userspecific<br />
filter conditions to be determined dynamically in runtime, for example, by querying specified tables or<br />
views. As a result, the same analytic privilege can be applied to many users, while the filter values for authorization<br />
can be updated and changed independently in the relevant database tables. In addition, application developers<br />
have full control not only to design and manage such filter conditions, but also to design the logic for obtaining the<br />
relevant filter values for the individual user at runtime.<br />
Procedures used to define filter conditions must have the following properties:<br />
● They must be DEFINER procedures.<br />
● They must be read-only procedures.<br />
● A procedure with a predefined signature must be used. The following conditions apply:<br />
○ No input parameter<br />
○ Only 1 output parameter as table type with one single column for the IN operator<br />
○ Only 1 output parameter of a scalar type for all unary operators, such as EQUAL<br />
○ Only 2 output parameters of a scalar type for the binary operator BETWEEN<br />
● Only the following data types are supported as the scalar types and the data type of the column in the table<br />
type:<br />
○ Date/Time types DATE, TIME, SECONDDATE, and TIMESTAMP<br />
○ Numeric types TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, REAL, and DOUBLE<br />
○ Character string types VARCHAR and NVARCHAR<br />
○ Binary type VARBINARY<br />
When the procedure is executed as part of the authorization check in runtime, the following constraints apply:<br />
● The user who must be authorized is the database user who executes the query accessing a secured view. This<br />
is the session user. The database table or view used in the procedure should therefore contain a column to<br />
store the user name of the session user. The procedure can then filter by this column using the SQL function<br />
SESSION_USER. This table or view should only be accessible to the procedure owner.<br />
● The user executing the procedure is the _SYS_REPO user. In the case of procedures activated in the <strong>SAP</strong><br />
<strong>HANA</strong> modeler, _SYS_REPO is the owner of the procedures. For procedures created in SQL, the EXECUTE<br />
privilege on the procedure must be granted to the _SYS_REPO user.<br />
● If the procedure fails to execute, the user’s query stops processing and a “Not authorized” error is returned .<br />
The root cause can be investigated in the error trace file of the indexserver,<br />
indexserver_alert_.trc.<br />
When designing and implementing procedures as filter for dynamic analytic privileges, bear the following in mind:<br />
● To avoid a recursive analytic privilege check, the procedures should only select from database tables or views<br />
that are not subject to an authorization check based on analytic privileges. In particular, views activated in the<br />
<strong>SAP</strong> <strong>HANA</strong> modeler are to be avoided completely as they are automatically registered for the analytic<br />
privilege check.<br />
● The execution of procedures in analytic privileges slows down query processing compared to analytic<br />
privileges containing only static filters. Therefore, procedures used in analytic privileges must be designed<br />
carefully.<br />
336<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Runtime Authorization Check of Analytic Privileges<br />
When a user requests access to data stored in an attribute, analytic, or calculation view, an authorization check<br />
based on analytic privileges is performed and the data returned to the user is filtered accordingly. Access to a<br />
view and the way in which results are filtered depend on whether the view is independent or associated with other<br />
modeling views (dependent views).<br />
Independent Views<br />
The authorization check for a view that is not defined on another modeling view is as follows:<br />
1. The user requests access to an individual view, for example with a SELECT query.<br />
This is possible if the both of the following prerequisites are met:<br />
○ The user has been granted the SQL privilege SELECT on the view or the schema in which it is located.<br />
○ The user has been granted an analytic privilege that is applicable to the view. An analytic privilege is<br />
applicable to a view if it contains the view in the view restriction and at least one filter on one attribute of<br />
the view.<br />
Note: The user does not require the SELECT privilege on the underlying base tables or views of the<br />
modeling view.<br />
2. The authorization check determines the analytic privileges that are relevant for the current user and view.<br />
Relevant analytic privileges are those that met all of the following criteria:<br />
○ Analytic privileges previously granted to the user, either directly or indirectly through a role<br />
○ Analytic privileges with a view restriction that includes the accessed view<br />
○ Analytic privileges with a currently valid validity restriction<br />
Note: This check is always positive for analytic privileges created and activated in the <strong>SAP</strong> <strong>HANA</strong><br />
modeler.<br />
○ Analytic privileges with an activity restriction covering the activity requested by the query are considered<br />
Note: This check is always positive for analytic privileges created and activated in the <strong>SAP</strong> <strong>HANA</strong><br />
modeler.<br />
○ Analytic privileges with dimension restrictions covering some of the view’s attributes<br />
3. If no relevant analytic privileges are found, the user’s queries are rejected with a “Not authorized” error.<br />
This means that even though the user has the SELECT privilege on the view, access is not possible.<br />
If the user does have a relevant analytic privilege but does not have the SELECT privilege on the view, access<br />
is also not possible. If relevant analytic privileges are found, the authorization check evaluates the value filters<br />
specified in the dimension restrictions and presents the appropriate data to the user.<br />
Note: Multiple dimension restrictions and/or multiple value filters are combined as described in the<br />
section on the structure of analytic privileges.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 337
Dependent Views<br />
Analytic views can be defined on attribute views, and calculation views that are defined on other modeling views. If<br />
a user requests access to such a view that is dependent on another view, the behavior of the authorization check<br />
varies as follows:<br />
● Analytic view associated with attribute view(s)<br />
A user can access an analytic view with associated attribute view(s) if one of the following prerequisites is<br />
met:<br />
○ The user has been granted an analytic privilege on the analytic view itself.<br />
○ The user has been granted an analytic privilege on an underlying attribute view.<br />
Result filtering is performed by a logical OR combination of all analytic privileges found on the analytic view<br />
and on its underlying attribute views.<br />
An analytic privilege on an analytic view with dependent attributes therefore does not restrict data access to<br />
the view, but rather increases it because the privilege on the analytic view is combined with privileges defined<br />
on the associated attribute views using logical OR.<br />
● Calculation view based on other view(s)<br />
A user can access a calculation view based on other view(s) if both of the following prerequisites are met:<br />
○ The user has been granted an analytic privilege on the calculation view.<br />
○ The user has been granted an analytic privilege on all underlying views if they are attribute, analytic, or<br />
calculation views.<br />
Result filtering is performed for each individual view. The underlying attribute, analytic, calculation views are<br />
authorized and filtered using the analytic privileges relevant for these views. The result of the top-level<br />
calculation view is then filtered using the analytic privileges defined on the calculation view itself.<br />
An analytic privilege on a calculation view based on other view(s) therefore further restricts data access to the<br />
calculation view as the privilege is evaluated on top of the result filtered by the analytic privileges defined on<br />
the underlying views (corresponding to a logical AND combination).<br />
Creation and Management of Analytic Privileges<br />
Analytic privileges can be created, dropped, and changed in the <strong>SAP</strong> <strong>HANA</strong> modeler and using SQL statements.<br />
The <strong>SAP</strong> <strong>HANA</strong> modeler should be used in all cases except if you are creating analytic privileges that use<br />
dynamic procedure-based value filters.<br />
To create analytic privileges, the system privilege CREATE STRUCTURED PRIVILEGE is required. To drop analytic<br />
privileges, the system privilege STRUCTUREDPRIVILEGE ADMIN is required.<br />
In the <strong>SAP</strong> <strong>HANA</strong> modeler, repository objects are technically created by the technical user _SYS_REPO, which by<br />
default has the system privileges for both creating and dropping analytic privileges. To be able to create, activate,<br />
drop, and redeploy analytic privileges in the <strong>SAP</strong> <strong>HANA</strong> modeler therefore, a database user requires the package<br />
privileges REPO.EDIT_NATIVE_OBJECTS and REPO.ACTIVATE_NATIVE_OBJECTS for the relevant package.<br />
338<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Implications of Creating Analytic Privileges Using SQL<br />
The <strong>SAP</strong> <strong>HANA</strong> modeler is the recommended method for creating and managing analytic privileges. However, it is<br />
necessary to use SQL to implement those features of analytic privileges not available in the modeler, that is,<br />
dynamic, procedure-based value filters as attribute restrictions.<br />
In the <strong>SAP</strong> <strong>HANA</strong> modeler, analytic privileges are created as design-time repository objects owned by the<br />
technical user _SYS_REPO. They must be activated to become runtime objects available in the database. Analytic<br />
privileges created using SQL statements are activated immediately. However, they are also owned by the<br />
database user who executes the SQL statements. This is the main disadvantage of using SQL to create analytic<br />
privileges. If the database user who created the analytic privilege is deleted, all objects owned by the user will also<br />
be deleted. Therefore, if you are using SQL to create analytic privileges, we recommend that you create a<br />
dedicated database user (that is, a technical user) for this purpose to avoid the potential loss of complex modeled<br />
privileges.<br />
An additional disadvantage of creating analytic privileges using SQL is that these analytic privileges are not in the<br />
<strong>SAP</strong> <strong>HANA</strong> repository and they cannot be transported between different systems.<br />
Granting and Revoking Analytic Privileges<br />
Analytic privileges are granted and revoked as part of user provisioning.<br />
If the analytic privilege was created and activated using the <strong>SAP</strong> <strong>HANA</strong> modeler, the analytic privilege is owned by<br />
the _SYS_REPO user. Therefore, to be able to grant and revoke the analytic privilege, a user needs the privilege<br />
EXECUTE on the procedures GRANT_ACTIVATED_ANALYTICAL_PRIVILEGE and<br />
REVOKE_ACTIVATED_ANALYTICAL_PRIVILEGE respectively.<br />
If the analytic privilege was created using SQL, only the owner (that is, the creator) of the analytic privilege can<br />
grant and revoke it.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Administration <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Example: Creating an Analytic Privilege with Dynamic Value Filter<br />
This example shows you how to create an analytic privilege that contains a dynamic procedure-based value filter<br />
and a fixed value filter in the attribute restriction.<br />
Assume you want to restrict access to product data in secured views as follows:<br />
● Users should only see products beginning with ELECTRO, or<br />
● Users should only see products for which they are specifically authorized. This information is contained in the<br />
database table PRODUCT_AUTHORIZATION_TABLE in the schema AUTHORIZATION.<br />
To be able to implement the second filter condition, you need to create a procedure that will determine which<br />
products a user is authorized to see by querying the table PRODUCT_AUTHORIZATION_TABLE.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 339
1. Create the table type for the output parameter of the procedure:<br />
CREATE TYPE "AUTHORIZATION"."PRODUCT_OUTPUT" AS TABLE("PRODUCT" int);<br />
2. Create the table that the procedure will use to check authorization:<br />
CREATE TABLE "AUTHORIZATION","PRODUCT_AUTHORIZATION_TABLE" ("USER_NAME"<br />
NVARCHAR(128), "PRODUCT" int);<br />
3. Create the procedure that will determine which products the database user executing the query is authorized<br />
to see based on information contained in the product authorization table:<br />
CREATE PROCEDURE "AUTHORIZATION"."DETERMINE_AUTHORIZED_PRODUCT_FOR_USER"<br />
(OUT VAL "AUTHORIZATION"."PRODUCT_OUTPUT")<br />
LANGUAGE SQLSCRIPT SQL SECURITY DEFINER READS SQL DATA AS<br />
BEGIN<br />
VAL = SELECT PRODUCT FROM<br />
"AUTHORIZATION"."PRODUCT_AUTHORIZATION_TABLE” WHERE USER_NAME =<br />
SESSION_USER;<br />
END;<br />
Note: The session user is the database user who is executing the query to access a secured view. This<br />
is therefore the user whose privileges must be checked. For this reason, the table or view used in the<br />
procedure should contain a column to store the user name so that the procedure can filter on this<br />
column using the SQL function SESSION_USER.<br />
4. Create the analytic privilege:<br />
340<br />
CREATE STRUCTURED PRIVILEGE '<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
';<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
Now when a database user requests access to a secured view containing product information, the data returned<br />
will be filtered according to the following condition:<br />
(product LIKE "ELECTRO*" OR product IN<br />
(AUTHORIZATION.DETERMINE_AUTHORIZED_PRODUCT_FOR_USER())<br />
12.4.5 Creating Analytic Privileges<br />
● To create, activate and drop the privilege you have system privileges CREATE STRUCTURED PRIVILEGE and<br />
STRUCTUREDPRIVILEGE ADMIN.<br />
● Make sure that both CREATE STRUCTURED PRIVILEGE and STRUCTUREDPRIVILEGE ADMIN are correctly<br />
owned by SYS_REPO user.<br />
● To activate and redeploy analytic privileges in the Modeler, a database user requires corresponding repository<br />
privileges, namely REPO.EDIT_NATIVE_OBJECTS and REPO.ACTIVATE_NATIVE_OBJECTS<br />
You apply analytic privileges when business users access values with certain combinations of dimension<br />
attributes. You can use analytic privileges to partition data among various users sharing the same data<br />
foundation. You can define restrictions for a selected group of models or apply them to all content models across<br />
packages.<br />
After activation, an analytic privilege needs to be assigned to a user before taking any effect. The user views the<br />
filtered data based on the restrictions defined in the analytic privilege. If no analytic privilege applicable for models<br />
is assigned to a user, he cannot access the model. If a user is assigned to multiple analytic privileges, the<br />
privileges are combined with OR conditions.<br />
Remember: In addition to the analytic privileges, a user needs SQL Select privileges on the generated<br />
column views.<br />
The generated column views adhere to the following naming conventions:<br />
For a view “MyView” in package “p1.p2” (i.e. subpackage p2 of package p1) the generated column view lies in<br />
schema _SYS_BIC and is named “_SYS_BIC”.”p1.p2/MyView”. Ensure that the users who are allowed to see the<br />
view have select privileges on the view (or the entire schema _SYS_BIC).<br />
Note: Multiple restrictions applied on the same column are combined by OR. However, restrictions across<br />
several columns are always combined by AND.<br />
1. Set Parameters for the Analytic Privilege<br />
a) In the Modeler perspective, expand the system node from the Navigator panel.<br />
b) Expand the Content node.<br />
c) Select the required package.<br />
d) From the context menu, choose New Analytic Privilege .<br />
1. Enter a name and description for the analytic privilege, and choose Next.<br />
2. Select the information models that you want to use for applying restrictions.<br />
3. Choose Finish.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
Tip: You can choose to add more models in the editor pane.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 341
2. Add Attributes<br />
a) If you want to add restrictions for all models, select the Applicable to all Information Models option.<br />
Note: If you do not select this option, the restrictions you create apply only to the secured list of<br />
models available in the Reference Models panel that you selected above.<br />
b) In the Associated Attributes Restrictions panel, choose Add to select the attributes for defining<br />
restrictions.<br />
c) Choose OK.<br />
3. Assign Restrictions<br />
Note: If you do not add any attributes for restrictions there will be unrestricted access to the<br />
selected models or to all the models (if Applicable to all the Information Models option is selected).<br />
a) In the Assign Restrictions pane, choose Add to add value restriction for the selected attributes.<br />
b) Select the required operator and enter a value (manually or via Value Help dialog).<br />
Remember: To activate the analytic privilege, you must assign a minimum of one restriction to each<br />
attribute.<br />
4. Activate the analytic privilege using the Save and Activate option in the editor.<br />
Note: Select the Save and Activate All option to activate the privilege along with all the required<br />
objects.<br />
5. Assign the privilege to a user<br />
342<br />
a) In the Navigator panel, navigate the Security Authorizations Users node.<br />
b) Select a user.<br />
c) In the context menu, choose Open.<br />
d) Choose Analytic Privileges tab page, and add the privilege.<br />
e) From the editor toolbar, choose Deploy.<br />
● Consider an analytic view (without fields coming from attribute views) or a calculation view SALES,<br />
which is added as part of an analytic privilege’s secured models having the following data.<br />
CUST_ID CUST_GROUP SALES<br />
1 GRP1 1000<br />
2 GRP2 1500<br />
3 GRP3 1200<br />
1 GRP4 1300<br />
If you create a restriction on column CUST_ID to filter data for CUST_ID 1 and 2, the conditions are<br />
combined with OR and the data available for a user is:<br />
CUST_ID CUST_GROUP SALES<br />
1 GRP1 1000<br />
2 GRP2 1500<br />
1 GRP4 1300<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
If you create restrictions on columns CUST_ID and CUST_GROUP such as CUST_ID = 1 and<br />
CUST_GROUP = 1, the conditions are combined with AND, and the data available for a user is:<br />
CUST_ID CUST_GROUP SALES<br />
1 GRP1 1000<br />
Note:<br />
○ The technical name used for attributes of calculation views and private attributes of<br />
analytic views, is the same as that of the attribute name. Hence any restriction applied to<br />
a private attribute of an analytic or calculation view attribute is also applied to any other<br />
private attribute of an analytic view and calculation view attribute having the same name.<br />
In the above example, if there is any other analytic view or calculation view, which is part<br />
of a privilege’s secured list of models, and has a field called “CUST_ID” (not coming from<br />
any attribute view), the data for these privileges also gets restricted.<br />
○ If Applicable to all information models is selected, any analytic view/calculation view (even<br />
if not part of the secured models) which has a (private) attribute called “CUST_ID”, the<br />
data for these privileges also get restricted.<br />
○ The behavior for the calculation view is the same as that of the analytic view described<br />
above.<br />
● Consider an attribute view CUSTOMER which is part of an analytic privilege’s secured list of models<br />
having the following data.<br />
CUST_ID COUNTRY MANDT<br />
1 IN 1<br />
2 IN 1<br />
3 US 1<br />
1 DE 2<br />
If you create a restriction on column CUST_ID to filter data for CUST_ID 1 and 2, the conditions are<br />
combined with OR and the data is shown as follows:<br />
CUST_ID COUNTRY MANDT<br />
1 IN 1<br />
2 IN 1<br />
1 DE 2<br />
If you create restrictions on columns CUST_ID and COUNTRY such as CUST_ID = 1 and COUNTRY =<br />
IN, the conditions are combined with AND, and the data available for a user is:<br />
CUST_ID COUNTRY MANDT<br />
1 IN 1000<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 343
Related Links<br />
Note:<br />
○ The technical name used for an attribute view attribute is /$. Hence, in the above example, the technical name for<br />
CUST_ID is mypackage/CUSTOMER$CUST_ID. This implies that if there is any other<br />
attribute view “STORE” which is a part of the analytic privilege and has CUST_ID as its<br />
attribute, it will not get restricted.<br />
○ Any analytic view that is part of the privilege’s secured list of models and has this attribute<br />
view as its required object, gets restricted using the technical name. In the example<br />
above, if an analytic view contains the attribute views CUSTOMER and STORE, both<br />
CUST_ID attributes are handled independently, because their internal technical name<br />
used for the privilege check are mypackage/CUSTOMER$CUST_ID and<br />
myotherpackage/STORE$UST_ID.<br />
○ If Applicable to all information models is selected, any analytic view (even if not part of the<br />
secured models) having this attribute view as its required object, also gets restricted.<br />
Structure of Analytic Privileges [page 332]<br />
An analytic privilege consists of a set of restrictions against which user access to a particular attribute view,<br />
analytic view, or calculation view is verified. Each restriction controls the authorization check on the restricted<br />
view using a set of value filters. A value filter defines a check condition that verifies whether or not the values<br />
of the view (or view columns) qualify for user access.<br />
Runtime Authorization Check of Analytic Privileges [page 337]<br />
When a user requests access to data stored in an attribute, analytic, or calculation view, an authorization<br />
check based on analytic privileges is performed and the data returned to the user is filtered accordingly.<br />
Access to a view and the way in which results are filtered depend on whether the view is independent or<br />
associated with other modeling views (dependent views).<br />
Dynamic Value Filters in the Attribute Restriction of Analytic Privileges [page 336]<br />
The attribute restriction of an analytic privilege specifies the value range that the user is permitted to access<br />
using value filters. In addition to static scalar values, stored procedures can be used to define filters. This<br />
allows user-specific filter conditions to be determined dynamically in runtime, for example, by querying<br />
specified tables or views. As a result, the same analytic privilege can be applied to many users, while the filter<br />
values for authorization can be updated and changed independently in the relevant database tables. In<br />
addition, application developers have full control not only to design and manage such filter conditions, but also<br />
to design the logic for obtaining the relevant filter values for the individual user at runtime.<br />
Creation and Management of Analytic Privileges [page 338]<br />
Analytic privileges can be created, dropped, and changed in the <strong>SAP</strong> <strong>HANA</strong> modeler and using SQL<br />
statements. The <strong>SAP</strong> <strong>HANA</strong> modeler should be used in all cases except if you are creating analytic privileges<br />
that use dynamic procedure-based value filters.<br />
Example: Creating an Analytic Privilege with Dynamic Value Filter [page 339]<br />
This example shows you how to create an analytic privilege that contains a dynamic procedure-based value<br />
filter and a fixed value filter in the attribute restriction.<br />
344<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
12.4.6 Granting Privileges to Users<br />
Privileges can be granted to database users either directly, or indirectly through roles that they have been<br />
granted. In this case, the privileges are inherited. Roles are the standard mechanism of granting privileges to<br />
users.<br />
To be able to grant and revoke privileges and roles to and from users and roles, the following prerequisites must<br />
be met:<br />
Action Prerequisite<br />
Grant system privilege, object privilege, or package<br />
privilege to user or role<br />
Granting user must have the privilege being granted<br />
and be authorized to grant it to other users and roles<br />
Grant analytic privilege to user or role Granting user must have the object privilege EXECUTE<br />
Grant object privilege on activated modeled objects,<br />
such as calculation views, to user or role<br />
on the procedure<br />
GRANT_ACTIVATED_ANALYTICAL_PRIVILEGE<br />
Granting user must have the object privilege EXECUTE<br />
on the procedure<br />
GRANT_PRIVILEGE_ON_ACTIVATED_CONTENT<br />
Grant role created in runtime to user or role ● Granting user must have the role being granted<br />
and be authorized to grant it to other users and<br />
roles, or<br />
● Granting user must be have the system privilege<br />
ROLE ADMIN<br />
Grant role created in the repository to user or role Granting user must have the object privilege EXECUTE<br />
on the procedure GRANT_ACTIVATED_ROLE<br />
Grant application privilege Granting user must have the object privilege EXECUTE<br />
Grant object privilege on schema containing activated<br />
modeled objects, such as calculation views, to user or<br />
role<br />
Revoke system privilege, object privilege, or package<br />
privilege from user or role<br />
Revoke object privilege on schema activated<br />
containing modeled objects, such as calculation views,<br />
from user or role<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
on the procedure GRANT_APPLICATION_PRIVILEGE<br />
Granting user must have the object privilege EXECUTE<br />
on the procedure<br />
GRANT_SCHEMA_PRIVILEGE_ON_ACTIVATED_CONT<br />
ENT<br />
Revoking user must be the user who granted the<br />
privilege<br />
Revoking user must have the object privilege EXECUTE<br />
on the procedure<br />
REVOKE_SCHEMA_PRIVILEGE_ON_ACTIVATED_CON<br />
TENT<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 345
Action Prerequisite<br />
Revoke analytic privilege from user or role Revoking user must have the object privilege EXECUTE<br />
on the procedure<br />
REVOKE_ACTIVATED_ANALYTICAL_PRIVILEGE<br />
Revoke role created in runtime from user or role Revoking user must be the user who granted the role<br />
Revoke role created in the repository from user or role Revoking user must have the object privilege EXECUTE<br />
on the procedure REVOKE_ACTIVATED_ROLE<br />
Revoke application privilege Revoking user must have the object privilege EXECUTE<br />
Revoke object privilege on activated modeled objects,<br />
such as calculation views from user or role<br />
1. In the Navigator view, choose Security Users .<br />
on the procedure REVOKE_APPLICATION_PRIVILEGE<br />
Revoking user must have the object privilege EXECUTE<br />
on the procedure<br />
REVOKE_PRIVILEGE_ON_ACTIVATED_CONTENT<br />
2. Open the relevant user and grant the required roles and privileges (object privileges, analytic privileges,<br />
system privileges, and package privileges) to the user.<br />
To grant a role or privilege, choose the button and search for the required role or privilege.<br />
To allow the user to pass on his or her privileges to other users, select Grantable to other users and roles.<br />
Note: This option is not available if you are granting a role that was created in the repository.<br />
Note: You cannot grant application privileges directly to users in the <strong>SAP</strong> <strong>HANA</strong> studio. It is<br />
recommended that you grant application privileges to roles created in the repository and then grant<br />
the role to the user.<br />
3. Choose the (Deploy) button to save the changes.<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Administration<br />
12.5 Application Access<br />
When you develop and deploy applications in the context of <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong><br />
<strong>HANA</strong> XS), you must define the application descriptors, which describe the framework in which the application<br />
runs. This application framework includes the root point in the package hierarchy where content is to be served to<br />
client requests, whether or not the application is permitted to expose data to client requests, what kind of access<br />
to the data is allowed, and what if any privileges are required to perform actions on application-related packages<br />
and package content. The application descriptors include the following files:<br />
● Application-descriptor file<br />
346<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations
The location of the application-descriptor file defines the root path of the resources exposed to client<br />
requests by the application you develop. You can further restrict access using the application-access and<br />
application-privileges files.<br />
● Application-Access File<br />
The application-access file enables you to specify who or what is authorized to access the content exposed by<br />
a <strong>SAP</strong> <strong>HANA</strong> XS application package and what content they are allowed to see. You can use keywords in the<br />
application-access file to set authentication rules, define package-privilege levels (for example, EXECUTE or<br />
ADMIN), specify the connection security level (for example, SSL/HTTPS), allow or prevent the creation of<br />
entity tags (Etags), and so on. You can also define rewrite rules for URLs exposed by an application, for<br />
example, to hide internal details of URL paths from external users, clients, and search engines.<br />
● Application-Privileges File<br />
The application-privileges file enables you to define the authorization privileges required for access to an <strong>SAP</strong><br />
<strong>HANA</strong> XS application, for example, to start the application (EXECUTE) or to perform administrative actions on<br />
an application (ADMIN). The privileges defined here are activated for a particular application in the<br />
application-access file. These privileges can be checked by an application at runtime. Privileges defined apply<br />
to the package where the privileges file is located as well as any packages further down the package hierarchy<br />
unless an additional privileges file is present, for example, in a subpackage.<br />
Related Links<br />
Note: An additional access-related file, the SQL-connection configuration file, enables you to execute SQL<br />
statements from inside your <strong>SAP</strong> <strong>HANA</strong> XS JavaScript application with credentials that are different to the<br />
credentials of the requesting user. Each SQL-connection configuration object has a unique name, and the<br />
administrator can assign specific, individual database users to this configuration.<br />
The Application-Descriptor File [page 49]<br />
Each application that you want to develop and deploy on <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong><br />
<strong>HANA</strong> XS) must have an application descriptor file. The application descriptor is the core file that you use to<br />
describe an application's framework within <strong>SAP</strong> <strong>HANA</strong> XS.<br />
The Application-Access File [page 50]<br />
<strong>SAP</strong> <strong>HANA</strong> XS enables you to define access to each individual application package that you want to develop<br />
and deploy.<br />
The Application-Privileges File [page 59]<br />
In <strong>SAP</strong> <strong>HANA</strong> Extended Application Services (<strong>SAP</strong> <strong>HANA</strong> XS), the application-privileges (.xssprivileges)<br />
file can be used to create or define the authorization privileges required for access to an <strong>SAP</strong> <strong>HANA</strong> XS<br />
application, for example, to start the application or to perform administrative actions on an application. These<br />
privileges can be checked by an application at runtime.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Setting Up Roles and Authorizations<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 347
13 Implementing Lifecycle<br />
Management<br />
13.1 <strong>SAP</strong> <strong>HANA</strong> Delivery Units<br />
In <strong>SAP</strong> <strong>HANA</strong>, the delivery unit (DU) is the vehicle that lifecycle management (LCM) uses to ship one or more<br />
software components from <strong>SAP</strong> (or a partner) to a customer .<br />
Delivery Units correspond to an "application" with versions, for which support packages and patches are<br />
delivered. Delivery units are not an equivalent to development classes; they are similar to Software Component<br />
Versions in the Product Availability Matrix (PAM). You can also use the delivery unit to transport repository<br />
content between <strong>SAP</strong> <strong>HANA</strong> systems, for example, between development systems or between development and<br />
productive systems.<br />
Note: A governance plan exists for the naming of delivery units and the package structure.<br />
A delivery unit is identified by the following key properties:<br />
● Vendor<br />
Used primarily to define the identity of the company producing the software component to deliver, for<br />
example, "sap". However, vendor can also be used to specify any customer implementing <strong>SAP</strong> <strong>HANA</strong>. To<br />
create a delivery unit, it is a prerequisite to maintain a vendor in your system.<br />
● Name<br />
Used to identify the software component to be delivered<br />
Although a vendor might provide multiple versions of a delivery unit in parallel, only one version of a delivery unit<br />
can be installed in a <strong>HANA</strong> system at any one time. In addition, duplicate names are not allowed for delivery units.<br />
<strong>SAP</strong> <strong>HANA</strong> treats delivery units and their versions as software components and software-component versions.<br />
Software components and software-component versions are usually shipped as part of a product (product<br />
version).<br />
Note: If you try to create a delivery unit using a name that already exists in your system, you will receive a<br />
validation error. A validation error also occurs if the check for a valid vendor ID does not find a suitable<br />
entry.<br />
13.2 The <strong>SAP</strong> <strong>HANA</strong> Delivery-Unit Lifecycle<br />
In <strong>SAP</strong> <strong>HANA</strong>, lifecycle management (LCM) includes all the activities you need to plan and perform to ensure that<br />
the software components you develop for <strong>SAP</strong> <strong>HANA</strong> Application Services are produced and shipped in a<br />
regulated way that meets the requirements laid out for the <strong>SAP</strong> <strong>HANA</strong> platform.<br />
348<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management
For example, you need to plan, manage, and maintain the application versions you want to ship, and you need to<br />
ensure that a stable plan exists to provide support for existing and all future versions of your application.<br />
<strong>SAP</strong> <strong>HANA</strong> lifecycle management uses the delivery unit (DU) is a vehicle to ship one or more software<br />
components from <strong>SAP</strong> (or a partner) to a customer. Delivery Units correspond to an "application" with versions,<br />
for which support packages and patches are delivered. You can also use the delivery unit to transport content<br />
between <strong>SAP</strong> <strong>HANA</strong> systems, for example, between development systems or between development and<br />
productive systems.<br />
Note: Delivery units are not to be confused with development classes; delivery units are similar to<br />
software component versions in the Product Availability Matrix (PAM).<br />
The Application-Development Lifecycle<br />
Application development on <strong>SAP</strong> <strong>HANA</strong> requires a server-centric life cycle for design-time objects, which are the<br />
development artifacts that you store in the <strong>SAP</strong> <strong>HANA</strong> repository. As an application developer, you check out<br />
design-time content from the repository and edit a copy of the checked-out artifact in the local file system on the<br />
your personal computer (PC). The following steps provide a brief, high-level overview of the development lifecycle<br />
for design-time content:<br />
1. Check out design-time content.<br />
Check out the package containing the design-time artifacts you want to work on (if the package already<br />
exists).<br />
2. Edit the design-time content.<br />
Edit the copies of the design-time artifacts, which are stored in your <strong>SAP</strong> <strong>HANA</strong> repository "workspace" on<br />
your local file system; the local copies of the design-time artifacts are created during the checkout process.<br />
3. Commit changes to design-time content.<br />
Committing the changes you have made to the design-time artifacts creates new versions of the artifacts in<br />
the <strong>SAP</strong> <strong>HANA</strong> repository. Note that identical (unchanged) versions of a file are not committed.<br />
4. Activate changes to design-time content.<br />
Activating the changes you have made to the design-time artifacts makes these changes available to<br />
applications and other users, creating runtime objects where necessary.<br />
13.3 Exporting Delivery Units<br />
Exporting a delivery unit (with all packages and dependencies) is the mechanism <strong>SAP</strong> <strong>HANA</strong> uses to enable the<br />
transfer of delivery units between systems, for example, to transport application content between development<br />
systems of from a development system to a consolidation system.<br />
The <strong>SAP</strong> <strong>HANA</strong> studio includes a mechanism that enables you to export and import delivery units. You can use the<br />
export feature to create an image of a delivery unit, which you can store either on the <strong>SAP</strong> <strong>HANA</strong> server or in the<br />
file system of a selected client for future import to another system. You can also export development objects as<br />
an archive that you can send to <strong>SAP</strong> support or share with other members of the development team.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 349
To export a delivery unit, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
Ensure that the <strong>SAP</strong> <strong>HANA</strong> studio is connected to the <strong>SAP</strong> <strong>HANA</strong> system hosting the delivery unit you want to<br />
export. If this is not the case, choose Select System... and change the system.<br />
2. In the File menu, choose Export....<br />
3. Select the export destination.<br />
The export destination enables you to specify the purpose for which you want to export the packages that<br />
make up the export archive. The option you choose determines the contents of the export archive. In most<br />
cases, you would choose the Delivery Unit option, which includes everything you need to transport the<br />
application-development structure to another system . However, you can choose from the following<br />
additional export destination options:<br />
○ <strong>Developer</strong> Mode<br />
Includes most objects and data, but does not include translatable text bundles<br />
○ <strong>SAP</strong> Support Mode<br />
Includes only the active version of objects and any data required by <strong>SAP</strong> Support to reproduce an issue<br />
you have encountered and reported<br />
Specify the Delivery Unit option, for example, <strong>SAP</strong> <strong>HANA</strong> Content > Delivery Unit<br />
4. Select the source system; the system you want to export the delivery unit from.<br />
In the Systems for export screen area of the Delivery Unit dialog, select the <strong>SAP</strong> <strong>HANA</strong> system hosting the<br />
repository in which the delivery unit is located that you want to export and choose Next to confirm the<br />
selection..<br />
5. Select the delivery unit to export.<br />
For example, <strong>HANA</strong>_XS_DOCS<br />
6. Filter the contents of the export package according to a specified time stamp.<br />
This step is optional. You can choose to export a complete delivery unit, or only those parts of a delivery unit<br />
that were changed during a specified time interval, which you define in the Filter by Time screen area.<br />
7. Select a location for the exported delivery unit:<br />
a) Server<br />
The <strong>SAP</strong> <strong>HANA</strong> studio automatically selects a file location to export the delivery unit to.<br />
b) Client<br />
Browse to the location in the local file-system where you want to store the exported delivery unit.<br />
8. Choose Next to confirm the settings.<br />
9. Choose Finish to start the export operation.<br />
10. Confirm the export operation succeeded.<br />
350<br />
You can browse to the location in the file system and examine the package contents in a file explorer to make<br />
sure the package contains the required content.<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management
13.4 Importing Delivery Units<br />
Importing a delivery-unit archive is the mechanism <strong>SAP</strong> <strong>HANA</strong> uses to enable you to transport delivery units<br />
between systems, for example, to upload a delivery unit that was exported from another development system or<br />
saved as an archive on a local file system.<br />
The <strong>SAP</strong> <strong>HANA</strong> studio includes a mechanism that enables you to export and import delivery units. To import a<br />
delivery unit, perform the following steps:<br />
1. Start the <strong>SAP</strong> <strong>HANA</strong> studio.<br />
Ensure that the <strong>SAP</strong> <strong>HANA</strong> studio is connected to the <strong>SAP</strong> <strong>HANA</strong> system hosting the delivery unit you want to<br />
export. If this is not the case, choose Select System... and change the system.<br />
2. In the File menu, choose Import...<br />
3. Select the import mode. The choice you make determines the information you need to enter in the next steps.<br />
The import mode enables you to specify the purpose for which you want to import the packages that make up<br />
the import archive. In most cases, you would choose the Delivery Unit option, which includes everything you<br />
need to transport the application-development structure from another system . However, you can choose<br />
from the following additional import destination options:<br />
○ Data from local file<br />
Imports data from a comma-separated-list (CSV) file or a Microsoft Excel file stored on the local file<br />
system into a new or an existing table (and schema).<br />
○ <strong>Developer</strong> Mode<br />
Includes most objects and data, but does not include translatable text bundles. The import operation<br />
obeys the following rules regarding the contents of the imported archive:<br />
○ If a package with the same name as the one to be imported already exists on the target system, but<br />
the package languages differ, objects are imported with a warning message.<br />
○ If a package with the same name as the one to be imported does not already exist on the target<br />
system, then the respective package with its original language (fetched from the properties file) is<br />
created.<br />
○ For old objects where no related properties file exists, a package is created with its language set to<br />
the logon language of the current import session.<br />
○ Import <strong>SAP</strong> NetWeaver BW Models<br />
Imports <strong>SAP</strong> NetWeaver Business Warehouse (<strong>SAP</strong> NetWeaver BW) models that are InfoCubes<br />
optimized for<strong>SAP</strong> <strong>HANA</strong>, <strong>SAP</strong> <strong>HANA</strong>-optimized DataStore objects, and Query Snapshot InfoProviders to<br />
the <strong>SAP</strong> <strong>HANA</strong> modeling environment.<br />
Note: With this option, you must maintain connection details for the BW system you want to<br />
import from, for example, host name, instance ID, client number and so on. You can test the<br />
connection before continuing with the import operation.<br />
Specify the mode in which you want the data to be imported, for example, <strong>SAP</strong> <strong>HANA</strong> Content > Delivery<br />
Unit .<br />
4. Select the target system; the system you want to import the delivery unit into.<br />
In the Systems for export screen area of the Delivery Unit dialog, select the <strong>SAP</strong> <strong>HANA</strong> system hosting the<br />
repository into which you want to import the delivery unit and choose Next to confirm the selection.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 351
5. Select the file containing the delivery unit you want to import.<br />
a) Server<br />
The <strong>SAP</strong> <strong>HANA</strong> studio automatically displays a list of available files stored in the default location; use the<br />
drop-down list to choose the file you want to import.<br />
b) Client<br />
Browse to the location in the local file-system where the file you want to import is stored.<br />
Before starting the import operation, the <strong>SAP</strong> <strong>HANA</strong> studio compares the contents of the delivery unit<br />
selected for imported with the current status of the repository on the target system and displays the results in<br />
the Object import simulation screen area. Hover the cursor over the icons in the Status column for a brief<br />
description of the indicated status.<br />
6. Choose Finish to start the import operation.<br />
Use the Actions screen area to specify what action to take if an imported object already exists in the target<br />
repository, for example:<br />
○ Overwrite inactive versions<br />
Overwrite inactive versions in your inactive workspace with objects from the imported delivery unit.<br />
○ Activate objects<br />
Activate objects imported from the delivery unit.<br />
○ Bypass validation<br />
Do not perform the client-side validation check on imported objects.<br />
7. Check the status bar in the <strong>SAP</strong> <strong>HANA</strong> studio to follow the progress of the import operation.<br />
You can also check progress in the Current tag page of the Job Log view.<br />
8. Confirm the import operation succeeded.<br />
13.5 Translating Delivery Units<br />
<strong>SAP</strong> <strong>HANA</strong> includes features that enable you to translate package-related metadata texts, for example labels and<br />
menu items in the user interface. The translation typically occurs on a separate dedicated system.<br />
If you plan to translate the contents of the new delivery unit you create, you must maintain translation details. The<br />
details include the connection to the translation system that the translation team use to store the localized<br />
versions of the translated data. The text to be translated is uploaded from the <strong>SAP</strong> <strong>HANA</strong> repository to the<br />
translation system and then reimported to the repository after the translated text are complete. As part of the<br />
translation process for delivery units, you typically perform the following tasks<br />
1. Maintain translation details for each delivery unit<br />
Translation details includes both mandatory and optional information. Mandatory details to maintain include<br />
the terminology domain, for example, Financial Accounting (FI), or Production Planning (PP) and the name<br />
space for the text collection, which is used by the translation systems.<br />
2. Maintain the connection with the remote translation system<br />
You need to be able to exchange the translation texts between <strong>SAP</strong> <strong>HANA</strong> and the translation system.<br />
3. Upload translation data to the translation system<br />
352<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management
4. Download translated text to the <strong>SAP</strong> <strong>HANA</strong> repository<br />
13.5.1 <strong>SAP</strong> <strong>HANA</strong> Delivery-Unit Translation Details<br />
The <strong>SAP</strong> <strong>HANA</strong> repository includes features for translating package-related metadata texts. If you plan to<br />
translate the contents of the new delivery unit you create, you must maintain translation details.<br />
Translation details provide a brief overview of the type and current status of the text objects to be translated, for<br />
example, by specifying the technical area of the new delivery unit and indicating the current status of translation<br />
texts.<br />
Note: Translation text can include the following elements: UI strings (menus, dialog titles), error<br />
messages, and documentation, amongst other things. Package names and descriptions are also relevant<br />
for translation purposes as are the names and descriptions of database views, tables, columns, and so on.<br />
To make things easier for the translation team, you should maintain the following metadata for translation<br />
purposes; the metadata must be maintained at the package level:<br />
● Terminology domain (mandatory)<br />
The technical/product area with which your delivery unit (application) is associated, for example: AC<br />
(Accounting General), FI (Financial Accounting), or PP (Production Planning and Control). This enables<br />
translator teams to assign work to the most suitable experts, and allows the translators to make use of<br />
existing terminology databases. The terminology domain is used by <strong>SAP</strong> internal translation systems.<br />
● Text collection (mandatory)<br />
The name space for the text objects in the translation system. Technically, you can use any value, but the<br />
text-collection name space is similar to the package namespace used in <strong>SAP</strong> <strong>HANA</strong>, for example:<br />
"sap.hana.xs.docs". The value assigned to the Text collection field is used by <strong>SAP</strong> internal translation systems.<br />
● Hint<br />
An optional field that customers and partners can use to pass on notes concerning the text objects tagged for<br />
translation.<br />
● Text status<br />
An optional field that customers and partners can use to pass on information indicating the current stage in<br />
the translation-review process of the text objects, for example: "New", "In review", "Reviewed", "Approved",<br />
"Published", and so on.<br />
13.5.2 Maintaining Translation Details<br />
Translation details provide a brief overview of the type and current status of the text objects to be translated, for<br />
example, by specifying the technical area of the new delivery unit and indicating the current status of translation<br />
texts.<br />
If you plan to translate the contents of a delivery unit, you must maintain translation details. You can maintain the<br />
translation details when you create a new delivery unit or for existing delivery units. It is mandatory to maintain<br />
the following translation-related details:<br />
● Terminology domain<br />
The technical/product area with which your delivery unit (application) is associated, for example: AC<br />
(Accounting General), FI, or PP.<br />
● Text collection<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 353
The name space for the text objects in the translation system, for example, "sap.hana.xs.docs".<br />
1. In the <strong>SAP</strong> <strong>HANA</strong> studio, start the Modeler perspective.<br />
2. In the Navigator view, select the <strong>SAP</strong> <strong>HANA</strong> instance where the repository containing the delivery unit is<br />
located.<br />
3. Expand the Content node until you can see the package whose translation details you want to maintain.<br />
4. Maintain the translation details for the selected delivery unit, as follows:<br />
a) Right-click the package whose translation details you want to maintain and choose Edit.<br />
b) Choose Translation >> to display the Translation Details screen area at the bottom of the Edit Package<br />
Details dialog.<br />
c) Select a Terminology Domain from the drop-down list.<br />
d) Enter a Text collection name.<br />
e) Save the changes to the translation details.<br />
5. Save the changes to the delivery unit.<br />
6. Commit and activate the changes in the <strong>SAP</strong> <strong>HANA</strong> repository.<br />
354<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Implementing Lifecycle Management
14 Using Database Client Interfaces<br />
<strong>SAP</strong> <strong>HANA</strong> provides client interfaces for connecting applications so they can retrieve and update data.<br />
<strong>SAP</strong> <strong>HANA</strong> provides many methods for applications to access its data. For example, a spreadsheet application<br />
could use ODBO to consume analytic views and enable users to create pivot tables, or a Web application could use<br />
OData interfaces to access the data and display it.<br />
<strong>SAP</strong> <strong>HANA</strong> can expose data with the following interfaces:<br />
● Client interfaces, which are available as long as the <strong>SAP</strong> <strong>HANA</strong> clients are installed:<br />
○ ODBC<br />
○ ODBO<br />
○ JDBC<br />
● Web-based interfaces, which must be defined by the application developer, who determines what data to<br />
expose and to whom:<br />
○ OData<br />
○ XMLA<br />
○ Server-Side JavaScript<br />
Related Links<br />
<strong>SAP</strong> <strong>HANA</strong> Database - Client Installation <strong>Guide</strong><br />
Defining Web-based Data Access [page 164]<br />
<strong>SAP</strong> <strong>HANA</strong> extended application services (<strong>SAP</strong> <strong>HANA</strong> XS) provide applications and application developers<br />
with access to the <strong>SAP</strong> <strong>HANA</strong> database using a consumption model that is exposed via HTTP.<br />
14.1 Connecting via ODBC<br />
<strong>SAP</strong> <strong>HANA</strong> provides an ODBC driver for connecting applications to the database.<br />
Note: Make sure to use the 32-bit ODBC driver for 32-bit applications, and the 64-bit driver for 64-bit<br />
applications.<br />
1. Install the ODBC driver. The driver is installed as part of the <strong>SAP</strong> <strong>HANA</strong> client installation.<br />
2. Write code to create a connection to the database. You can use one of the following methods:<br />
○ Connection String (SQLDriverConnect): Use a connection string in the form:<br />
DRIVER={};UID=;PWD=;<br />
SERVERNODE=:;<br />
should be one of the following:<br />
○ HDBODBC: For 64-bit applications<br />
○ HDBODBC32: For 32-bit applications<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 355
should be 315, for example, 30015, if the instance is 00.<br />
The following is an example of a connection string:<br />
DRIVER={HDBODBC};UID=myUser;PWD=myPassword;SERVERNODE=myServer:30015;<br />
○ DSN (SQLConnect): Create a data source by running the odbcad32.exe tool. You can run this via a<br />
Related Links<br />
command line or via the Control Panel /Administrative Tools /Data Sources (ODBC) .<br />
Note:<br />
○ The application is located in the system32 directory. To create a data source for the 32-bit<br />
driver on a 64-bit Microsoft Windows machine, run the tool from the SysWOW64 directory.<br />
In the DSN tab, choose Add, select the <strong>SAP</strong> <strong>HANA</strong> driver, and select Finish. The following appears:<br />
You cannot enter a user name and password here. For the server and port, you can either enter a key<br />
created using the <strong>SAP</strong> <strong>HANA</strong> user store (which defines the server, port, user name and password), or you<br />
can enter a server and port (e.g., myServer:30015). If you enter a server and port, then the application<br />
must supply the user name and password when connecting.<br />
<strong>SAP</strong> <strong>HANA</strong> Database - Client Installation <strong>Guide</strong><br />
Using the User Store [page 356]<br />
14.1.1 Using the User Store<br />
The <strong>SAP</strong> <strong>HANA</strong> user store enables you to store connection information for connecting to an <strong>SAP</strong> <strong>HANA</strong> system.<br />
Instead of entering connection information each time you make a connection, you store the information, assign it<br />
a key, and use this key when making connections.<br />
This makes it easier to move between systems (for example, when executing SQL from the command line), and<br />
also keeps connection information, including user names and passwords, in a secure place.<br />
The <strong>SAP</strong> <strong>HANA</strong> user store is part of the client installation.<br />
356<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
1. In a command line, run the following:<br />
hdbuserstore.exe set : <br />
The server, port, user name and password are now stored in the user store. The key is a string you use to refer<br />
to this set of connection information.<br />
2. Use the key to reference a connection to a particular system. Always precede the key with an @, for example,<br />
@mykey.<br />
Use the key in the following ways:<br />
○ In the connection string, use the key for the SERVERNODE parameter, and do not include a user name<br />
and password, for example:<br />
SERVERNODE={@mykey};DRIVER={hdbodbc};<br />
○ In creating a DSN, enter the key (for example, @mykey) for the server and port.<br />
○ In testing your connection (by running odbcreg -t hdbodbc), use the key (for example, @mykey) for<br />
the server and port. If the connection is successful, you get something like this:<br />
The response includes a sample connection string using the key.<br />
Related Links<br />
Testing the ODBC Installation [page 357]<br />
You can test the installation of the ODBC driver and your ability to connect by using the odbcreg tool, which<br />
is part of the ODBC installation.<br />
14.1.2 Testing the ODBC Installation<br />
You can test the installation of the ODBC driver and your ability to connect by using the odbcreg tool, which is<br />
part of the ODBC installation.<br />
1. Open a command window.<br />
2. Start the odbcreg tool by enter a command in the form: odbcreg -t hdbcodbc (for 64-bit driver) or<br />
odbcreg32 -t hdbcodbc32 (for 32-bit driver).<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 357
If the driver is installed properly, you should get the ODBC login screen.<br />
Note: You can also run the command odbcreg -g or odbcreg32 -g to get a list of installed<br />
drivers. The <strong>SAP</strong> <strong>HANA</strong> driver is called HDBODBC.<br />
3. Test your ability to connect by entering connection information (system, port, user name and password) and<br />
select OK. The tool closes and the results of the test are printed in the command window.<br />
You can also run odbcreg -g to get a list of installed ODBC drivers, and check to make sure that the <strong>SAP</strong> <strong>HANA</strong><br />
driver (either HDBODBC or HDBODBC32) is installed.<br />
14.2 Connecting via JDBC<br />
<strong>SAP</strong> <strong>HANA</strong> provides a JDBC driver for connecting Java applications to the database.<br />
1. Install the JDBC driver.<br />
The driver (ngdbc.jar) is installed as part of the <strong>SAP</strong> <strong>HANA</strong> client installation and is located at:<br />
○ C:\Program Files\sap\hdbclient\ on Microsoft Windows platforms<br />
○ /usr/sap/hdbclient/ on Linux and UNIX platforms<br />
2. Add ngdbc.jar to your classpath.<br />
3. If you are on a version of Java earlier than Java 6, load the JDBC driver class, which is called<br />
com.sap.db.jdbc.Driver.<br />
4. Write Java code to create a connection to the database and execute SQL commands. Use a connection string<br />
in the form of jdbc:sap://:[/?]. For example:<br />
358<br />
jdbc:sap://myServer:30015/?autocommit=false<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
The port should be 315, for example, 30015, if the instance is 00.<br />
You can specify one or more failover servers by adding additional hosts, as in the following example:<br />
jdbc:sap://myServer:30015,failover1:30015,failover2:30015/?<br />
autocommit=false<br />
Related Links<br />
The following is an example of connecting to an <strong>SAP</strong> <strong>HANA</strong> server called myhdb, which was installed as<br />
instance 07, with user name myname and password mysecret. Make sure to change these for your<br />
system, and add the JDBC driver (ngdbc.jar) to your classpath.<br />
import java.sql.*;<br />
public class jdemo {<br />
public static void main(String[] argv) {<br />
Connection connection = null;<br />
try {<br />
connection = DriverManager.getConnection(<br />
"jdbc:sap://myhdb:30715/?<br />
autocommit=false",myname,mysecret);<br />
} catch (SQLException e) {<br />
System.err.println("Connection Failed. User/Passwd Error?");<br />
return;<br />
}<br />
if (connection != null) {<br />
try {<br />
System.out.println("Connection to <strong>HANA</strong> successful!");<br />
Statement stmt = connection.createStatement();<br />
ResultSet resultSet = stmt.executeQuery("Select 'hello<br />
world' from dummy");<br />
resultSet.next();<br />
String hello = resultSet.getString(1);<br />
System.out.println(hello);<br />
} catch (SQLException e) {<br />
System.err.println("Query failed!");<br />
}<br />
}<br />
}<br />
}<br />
<strong>SAP</strong> <strong>HANA</strong> Database - Client Installation <strong>Guide</strong><br />
14.2.1 Tracing JDBC Connections<br />
You can activate the JDBC trace to find errors while your application is connected to a database via JDBC.<br />
You must be logged on as the operating system user who started (or will start) the JDBC application.<br />
Note:<br />
● You always activate the JDBC trace for all JDBC applications that the current operating system user<br />
has started.<br />
● Configuration changes have an effect on all JDBC applications that the current operating system user<br />
has started.<br />
When the JDBC trace is activated, the JDBC driver logs on the client the following information:<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 359
● JDBC API calls called by the JDBC application<br />
● JDBC API call parameters<br />
● Executed SQL statements and their results<br />
The location of the trace file is determined by the trace options.<br />
Tracing via GUI<br />
You can start tracing by running the tracing configuration tool that includes a graphical user interface (GUI).<br />
Tracing via the GUI enables you to start and configure tracing without stopping and restarting your application<br />
that is connected via JDBC.<br />
1. On the client, enter the following command on the command line: java -jar <br />
\ngdbc.jar.<br />
2. Select Trace enabled.<br />
3. Select and modify the tracing options.<br />
4. Select OK.<br />
Tracing via Command Line<br />
You can start tracing by running the tracing configuration tool and sending commands via the command line.<br />
Tracing via the command line enables you to start and configure tracing without stopping and restarting your<br />
application that is connected via JDBC.<br />
1. Display the current configuration by running the command java -jar <br />
\ngdbc.jar.<br />
2. Select trace options by running the command java -jar \ngdbc.jar<br />
.<br />
3. Start tracing by running the command java -jar \ngdbc.jar TRACE ON.<br />
Related Links<br />
Trace Options<br />
Tracing via Connection String<br />
You can start tracing by adding an option in the connection string when creating a JDBC connection.<br />
Tracing via the connection string requires you to stop and restart your application that is making the JDBC<br />
connection. Also, with the connection string, you cannot turn off tracing or set any options except setting the<br />
trace filename.<br />
Add the trace option to the connection when creating a JDBC connection.<br />
Here is an example connection string that starts tracing:<br />
jdbc:sap://localhost:30015/?autocommit=false&trace=traceFile.txt<br />
The location of the trace file is determined by the trace options.<br />
Trace Options<br />
Options when enabling JDBC tracing.<br />
360<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
The first column shows the field name in the GUI-based tracing configuration tool, and the second column shows<br />
the command to enter when using the command-line tool.<br />
Table 16: Trace Options<br />
Option Command Line Option Description<br />
Trace enabled TRACE ON | OFF Starts and stops tracing<br />
Trace file folder No command-line option. The folder can be specified<br />
with the FILENAME option.<br />
Sets the directory where the system<br />
writes the trace files.<br />
When no folder is specified, the files<br />
are saved in the working directory of<br />
the application.<br />
Trace file name TRACE FILENAME [] Sets the name of the trace file.<br />
Limit file size TRACE SIZE [KB|MB|GB]<br />
To remove the size limit, use the following option:<br />
TRACE SIZE UNLIMITED<br />
Stop on error TRACE STOP ON ERROR <br />
To no longer stop on the specified error, use the<br />
following option:<br />
TRACE STOP ON ERROR OFF<br />
The system assigns each trace file<br />
an additional unique ID, so the file<br />
name is:<br />
_.prt<br />
The default file name is<br />
jdbctrace.<br />
Limits the size of each trace file.<br />
Stops writing the JDBC trace when<br />
the specified error code occurs.<br />
14.2.2 Valid Java-to-SQL Conversions<br />
<strong>SAP</strong> <strong>HANA</strong> allows each Java object to be converted to specific SQL types using the JDBC method<br />
PreparedStatement.setObject or RowSet.setObject.<br />
Some conversions may fail at runtime if the value passed is invalid.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 361
14.3 Connecting via ODBO<br />
<strong>SAP</strong> <strong>HANA</strong> provides an ODBO driver for connecting applications to the database and executing MDX statements.<br />
1. Install the ODBO driver. The driver is installed as part of the <strong>SAP</strong> <strong>HANA</strong> client installation.<br />
2. Specify in your client the provider name: <strong>SAP</strong>NewDBMDXProvider<br />
3. Create a connection string in the form of:<br />
;User ID=;Password=
3. In the Connection tab of the Data Link Properties window, enter the <strong>SAP</strong> <strong>HANA</strong> server name, instance number,<br />
user name and password.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 363
4. Select the cube from which you want to import data. <strong>SAP</strong> <strong>HANA</strong> analytic and calculation views are exposed as<br />
cubes.<br />
364<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
<strong>SAP</strong> <strong>HANA</strong> supports the following Microsoft Excel features:<br />
● Drilling down<br />
● Selection filtering<br />
● Top/bottom filters<br />
● Report filters<br />
● Member properties<br />
● Refresh cube<br />
● Convert PivotTable into formulas<br />
● Server formatting<br />
● Pre-modeled calculated members<br />
● Show/hide fields<br />
● Enhanced value and label filters<br />
● Insert slicer<br />
● Text search in report filter<br />
● PivotTable filter<br />
● Creation of named sets<br />
14.3.2 Multidimensional Expressions (MDX)<br />
Multidimensional Expressions (MDX) is a language you can use to query multidimensional data stored in OLAP<br />
cubes.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 365
MDX uses a multidimensional data model to enable navigation in multiple dimensions, levels, and up and down a<br />
hierarchy. With MDX, you can access pre-computed aggregates at specified positions (levels or members) in a<br />
hierarchy.<br />
Note: MDX is an open standard. However, <strong>SAP</strong> has developed extensions to MDX that are designed to<br />
enable faster and more efficient access to multidimensional data, for example, to serve specific <strong>SAP</strong><br />
<strong>HANA</strong> application requirements and to optimize the resultset for <strong>SAP</strong> <strong>HANA</strong> clients.<br />
MDX is implicitly a hierarchy-based paradigm. All members of all dimensions must belong to a hierarchy. Even if<br />
you do not explicitly create hierarchies in your <strong>SAP</strong> <strong>HANA</strong> data model, the <strong>SAP</strong> <strong>HANA</strong> modeler implicitly<br />
generates default hierarchies for each dimension. All identifiers that are used to uniquely identify hierarchies,<br />
levels and members in MDX statements (and metadata requests) embed the hierarchy name within the identifier.<br />
In <strong>SAP</strong> <strong>HANA</strong>, the standard use of MDX is to access <strong>SAP</strong> <strong>HANA</strong> models (for example, analytical and attribute<br />
views) that have been designed, validated and activated in the modeler in the <strong>SAP</strong> <strong>HANA</strong> studio. The studio<br />
provides a graphical design environment that enables detailed control over all aspects of the model and its<br />
language-context-sensitive runtime representation to users.<br />
MDX in <strong>SAP</strong> <strong>HANA</strong> uses a runtime cube model, which usually consists of an analytical (or calculation) view that<br />
represents data in which dimensions are modeled as attribute views. You can use the analytical view to specify<br />
whether a given attribute is intended for display purposes only or for aggregation. The key attributes of attribute<br />
views are linked to private attributes in an analytical view in order to connect the entities. One benefit of MDX in<br />
<strong>SAP</strong> <strong>HANA</strong> is the native support of hierarchies defined for attribute views.<br />
Note: MDX in <strong>SAP</strong> <strong>HANA</strong> includes native support of hierarchies defined for attribute views. <strong>SAP</strong> <strong>HANA</strong><br />
supports level-based and parent-child hierarchies and both types of hierarchies are accessible with MDX.<br />
<strong>SAP</strong> <strong>HANA</strong> supports the use of variables in MDX queries; the variables are a <strong>SAP</strong>-specific enhancement to<br />
standard MDX syntax. You can specify values for all mandatory variables that are defined in <strong>SAP</strong> <strong>HANA</strong> studio to<br />
various modeling entities. The following example illustrates how to declare <strong>SAP</strong> <strong>HANA</strong> variables and their values:<br />
MDX<br />
Select<br />
From [MINI_C1_VAR]<br />
Where [Measures].[M2_1_M3_CONV]<br />
<strong>SAP</strong> VARIABLES [VAR_VAT] including 10,<br />
[VAR_K2] including 112,<br />
[VAR_TARGET_CURRENCY] including 'EUR',<br />
14.3.3 MDX Functions<br />
MDX in <strong>SAP</strong> <strong>HANA</strong> supports a variety of standard MDX functions.<br />
Table 17: Supported MDX Functions<br />
Function Description<br />
Aggregate Returns a calculated value using the appropriate aggregate function, based on the<br />
aggregation type of the member.<br />
Ancestor Returns the ancestor of a member at a specified level or at a specific distance away<br />
in the hierarchy.<br />
Ancestors Returns a set of all ancestors of a member at a specified level or at a specific<br />
distance away in the hierarchy.<br />
Ascendants Returns the set of the ascendants of the member.<br />
366<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
Function Description<br />
Avg Returns the average value of a numeric expression evaluated over a set.<br />
BottomCount Returns a specified number of items from the bottom of a set, optionally sorting<br />
the set first.<br />
Children Returns the children of a member.<br />
ClosingPeriod Returns the last sibling among the descendants of a member at a specified level.<br />
Count Counts the number of members in the tuple.<br />
Cousin Returns the child member with the same relative position under a parent member<br />
as the specified child member.<br />
Crossjoin Returns the cross product of two sets.<br />
CurrentMember Returns the current member along a hierarchy.<br />
DefaultMember Returns the default member of a hierarchy.<br />
Descendants Returns the set of descendants of a member at a specified level or at a specific<br />
distance away in the hierarchy.<br />
Dimension Returns the hierarchy that contains a specified member or level.<br />
Dimensions Returns a hierarchy specified by a numeric or string expression.<br />
Distinct Returns a set, removing duplicate tuples from a specified set.<br />
DistinctCount Returns the number of distinct tuples in a set.<br />
DrillDownLevel Drills down the members of a set one level below the lowest level represented in the<br />
set, or to one level below an optional level of a member represented in the set.<br />
DrillDownLevelBottom Drills down the members of a specified count of bottom members of a set, at a<br />
specified level, to one level below.<br />
DrillDownLevelTop Drills down a specified count of top members of a set, at a specified level, to one<br />
level below.<br />
DrillDownMember Drills down the members in a specified set that are present in a second specified<br />
set.<br />
DrillDownMemberBottom Drills down the members in a specified set that are present in a second specified<br />
set, limiting the result set to a specified number of bottommost members.<br />
DrillDownMemberTop Drills down the members in a specified set that are present in a second specified<br />
set, limiting the result set to a specified number of topmost members.<br />
DrillUpLevel Drills up the members of a set that are below a specified level.<br />
DrillUpmember Drills up the members in a specified set that are present in a second specified set.<br />
Except Finds the difference between two sets, optionally retaining duplicates.<br />
Filter Returns the set resulting from filtering a set based on a search condition.<br />
FirstChild Returns the first child of a specified member.<br />
FirstSibling Returns the first child of the parent of a specified member.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 367
Function Description<br />
Generate Applies a set to each member of another set, and then joins the resulting sets by<br />
union. Alternatively, this function returns a concatenated string created by<br />
evaluating a string expression over a set.<br />
Head Returns the first specified number of elements in a set.<br />
Hierarchize Orders the members of a specified set in a hierarchy in natural or, optionally, postnatural<br />
order.<br />
Hierarchy<br />
Instr The InStr function finds the starting location of a substring within a specified string.<br />
Intersect Returns the intersection of two sets, optionally retaining duplicates.<br />
IsAncestor Returns true if the first member specified is an ancestor of the second member<br />
specified, else returns false.<br />
IsGeneration Returns true if the member specified is a leaf, else returns false.<br />
IsLeaf Returns true if the first member specified is an ancestor of the second member<br />
specified, else returns false.<br />
IsSibling Returns true if the first member specified is an sibling of the second member<br />
specified, else returns false.<br />
Item If an integer is specified, the Item function returns the tuple that is in the zerobased<br />
position specified by Index.<br />
IIF Returns one of values determined by a logical test.<br />
Lag Returns the member that is a specified number of positions prior to a specified<br />
member along the dimension of the member.<br />
LastChild Returns the last child of a specified member.<br />
LastPeriods Returns a set of members prior to and including a specified member.<br />
LastSibling Returns the last child of the parent of a specified member.<br />
Lead Returns the member that is a specified number of positions following a specified<br />
member along the dimension of the member.<br />
Leaves If a dimension name is specified, returns a set that contains the leaf members of<br />
the key attribute for the specified dimension.If a dimension name is not specified,<br />
the function returns a set that contains the leaf members of the entire cube.<br />
Left The Left function returns a string of a specified number of characters from the left<br />
side (beginning) of a specified string.<br />
Level Returns the level of a member.<br />
Levels Returns the level whose zero-based position in a dimension is specified by a<br />
numeric expression.<br />
Max Returns the maximum value of a numeric expression evaluated over a set.<br />
Member_caption Returns the caption of a member<br />
Members Returns the set of all members in a specified hierarchy.<br />
368<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
Function Description<br />
MembersAscendantsDesc<br />
endants<br />
Returns the set of specified members in a given hierarchy.<br />
Mid The Mid function returns a substring of a string argument.<br />
Min Returns the minimum value of a numeric expression evaluated over a set<br />
MTD Returns a set of members from the Month level in a Time dimension starting with<br />
the first period and ending with a specified member.<br />
Name Returns the name of a specified hierarchy or member.<br />
NextMember Returns the next member in the level that contains a specified member.<br />
NOT Performs a logical negation on a numeric expression.<br />
OpeningPeriod Returns the first sibling among the descendants of a specified level, optionally at a<br />
specified member.<br />
OR Performs a logical disjunction on two numeric expressions.<br />
Ordinal Returns the zero-based ordinal value associated with a specified level.<br />
ParallelPeriod Returns a member from a prior period in the same relative position as a specified<br />
member.<br />
Parent Returns the parent of a specified member.<br />
PeriodsToDate Returns a set of members (periods) from a specified level starting with the first<br />
member and ending with a specified member.<br />
PrevMember Returns the previous member in the level that contains a specified member.<br />
Properties Returns a string containing the value of the specified member property.<br />
QTD Returns a set of members from the Quarter level in a Time dimension starting with<br />
the first period and ending with a specified member.<br />
Range Performs a set operation that returns a naturally ordered set, with the two<br />
specified members as endpoints, and all members between the two specified<br />
members included as members of the set<br />
Right The Right function returns a string of a specified number of characters from the<br />
right side (end) of a specified string.<br />
Siblings Returns the set of siblings of a specified member, including the member itself.<br />
StrToMember Returns a member from a string expression in MDX format.<br />
StrToSet Constructs a set from a specified string expression in MDX format.<br />
StrToTuple Constructs a tuple from a specified string expression in MDX format.<br />
StrToValue Returns a value from a string expression<br />
Subset Returns a subset of tuples from a specified set.<br />
Sum Returns the sum of a numeric expression evaluated over a specified set.<br />
Tail Returns the last specified number of elements in a set.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 369
Function Description<br />
TopCount Returns a specified number of items from the topmost members of a specified set,<br />
optionally ordering the set first.<br />
Union Performs a set operation that returns a union of two sets, removing duplicate<br />
members.<br />
UniqueName Returns the unique name of a specified hierarchy.<br />
WTD Returns a set of members from the Week level in a Time dimension starting with<br />
the first period and ending with a specified member.<br />
YTD Returns a set of members from the Year level in a Time dimension starting with the<br />
first period and ending with a specified member.<br />
14.3.4 MDX Extensions<br />
<strong>SAP</strong> <strong>HANA</strong> supports several extensions to the MDX language, for example, additional predefined functions and<br />
support for variables.<br />
Sibling_Ordinal Intrinsic Property<br />
The object Member includes a property called Sibling_Ordinal, that is equal to the 0-based position of the<br />
member within its siblings.<br />
WITH<br />
MEMBER [Measures].[Termination Rate] AS<br />
[Measures].[NET_SALES] / [Measures].[BILLED_QUANTITY]<br />
SELECT<br />
{<br />
[Measures].[NET_SALES],<br />
[Measures].[BILLED_QUANTITY],<br />
[Measures].[Termination Rate]<br />
} ON COLUMNS,<br />
Descendants<br />
(<br />
[MDX_TEST_10_DISTRIBUTION_CHANNEL].<br />
[MDX_TEST_10_DISTRIBUTION_CHANNEL].[All].[(all)],<br />
1,<br />
SELF_AND_BEFORE<br />
)<br />
DIMENSION PROPERTIES SIBLING_ORDINAL ON ROWS<br />
FROM MDX_TEST_10_ITELO_SALES_DATA<br />
MembersAscendantsDescendants Function<br />
<strong>SAP</strong> <strong>HANA</strong> includes a new function called MembersAscendantsDescendants that enables you to get, for<br />
example, all ascendants and descendants of a specific member. This function improves on the standard MDX<br />
functions Ascendants and Descendants.<br />
The function can be called as follows:<br />
MembersAscendantsDescendants (, )<br />
● set: A set of members from a single hierarchy<br />
● flag: Indicates which related members to return, and can be one of the following:<br />
370<br />
○ MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
○ MEMBERS_AND_ASCENDANTS<br />
○ MEMBERS_AND_DESCENDANTS<br />
○ ASCENDANTS_AND_DESCENDANTS<br />
○ ONLY_ASCENDANTS<br />
○ ONLY_DESCENDANTS<br />
SELECT<br />
{ [Measures].[SALES] }<br />
ON COLUMNS,<br />
NON EMPTY<br />
{ Hierarchize( MembersAscendantsDescendants([JUICE_TIME].[TimeHier].<br />
[QUARTER].[3]:[JUICE_TIME].[TimeHier].[QUARTER].[4],<br />
MEMBERS_AND_ASCENDANTS_AND_DESCENDANTS )) }<br />
ON ROWS<br />
FROM [JUICE]<br />
SELECT<br />
{ [Measures].[SALES] }<br />
ON COLUMNS,<br />
NON EMPTY<br />
{ Hierarchize( MembersAscendantsDescendants([JUICE_TIME].[TimeHier].<br />
[QUARTER].[3]:[JUICE_TIME].[TimeHier].[QUARTER].[4],<br />
ONLY_ASCENDANTS )) }<br />
ON ROWS<br />
FROM [JUICE]<br />
Variables<br />
An MDX SELECT statement in <strong>SAP</strong> <strong>HANA</strong> enables you to send values for variables defined within modeling views.<br />
Analytic and calculation views can contain variables, that can be bound to specific attributes. When calling the<br />
view, you can send values for those variables. These variables can be used, for example, to filter the results.<br />
<strong>SAP</strong> <strong>HANA</strong> supports an extension to MDX whereby you can pass values for variables defined in views by adding a<br />
<strong>SAP</strong> Variables clause in your select statement. Here is the syntax for a Select statement:<br />
: [WITH ]<br />
SELECT [[,...]]<br />
FROM <br />
[WHERE <br />
<strong>SAP</strong> VARIABLES: [[,] …]]<br />
: [] <br />
: INCLUDING | EXCLUDING<br />
: = | > | >= | < |
[VAR_K2] including 112,<br />
[VAR_TARGET_CURRENCY] including 'EUR'<br />
The following specifies an interval for variable VAR_K2.<br />
SELECT NON EMPTY<br />
{<br />
[K2].[K2].Members<br />
}ON ROWS<br />
FROM [MINI_C1_VAR_SIMPLE]<br />
WHERE [Measures].[M3_CONV]<br />
<strong>SAP</strong> VARIABLES [VAR_K2] including [K2].[K2].&[122]:[K2].[K2].&[221]<br />
Metadata on Variables in Views<br />
<strong>SAP</strong> <strong>HANA</strong> includes the following set of tables that contain information about the variables defined for views:<br />
● BIMC_VARIABLE<br />
● BIMC_VARIABLE_ASSIGNMENT<br />
● BIMC_VARIABLE_VALUE<br />
● BIMC_VARIABLE_ODBO (virtual table)<br />
The tables enable, for example, an application to retrieve the variables defined for a view and create a user<br />
interface so the user can enter values.<br />
372<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
Using Database Client Interfaces
15 <strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> References<br />
The <strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong>'s <strong>Guide</strong> comes with the following language, API and other references.<br />
Name Link<br />
<strong>SAP</strong> <strong>HANA</strong> SQL Reference http://help.sap.com/hana/html/sqlmain.html<br />
<strong>SAP</strong> <strong>HANA</strong> SQLScript Reference http://help.sap.com/hana/hana_dev_sqlscript_en.pdf<br />
<strong>SAP</strong> <strong>HANA</strong> System Tables and Monitoring Views<br />
Reference<br />
http://help.sap.com/hana/html/monitor_views.html<br />
<strong>SAP</strong> <strong>HANA</strong> R Integration <strong>Guide</strong> http://help.sap.com/hana/hana_dev_r_emb_en.pdf<br />
<strong>SAP</strong> <strong>HANA</strong> Business Function Library (BFL) Reference http://help.sap.com/hana/hana_dev_bfl_en.pdf<br />
<strong>SAP</strong> <strong>HANA</strong> Predictive Analysis Library (PAL) Reference http://help.sap.com/hana/hana_dev_pal_en.pdf<br />
<strong>SAP</strong> <strong>HANA</strong> XS JavaScript Reference http://help.sap.com/hana/jsapi/index.html<br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> <strong>Guide</strong><br />
<strong>SAP</strong> <strong>HANA</strong> <strong>Developer</strong> References<br />
P U B L I C<br />
© 2012 <strong>SAP</strong> AG. All rights reserved. 373
www.sap.com/contactsap<br />
© 2012 <strong>SAP</strong> AG. All rights reserved.<br />
No part of this publication may be reproduced or transmitted in<br />
any form or for any purpose without the express permission of<br />
<strong>SAP</strong> AG.<br />
The information contained herein may be changed without prior<br />
notice.<br />
Some software products marketed by <strong>SAP</strong> AG and its distributors<br />
contain proprietary software components of other software<br />
vendors.<br />
Microsoft, Windows, Excel, Outlook, and PowerPoint are<br />
registered trademarks of Microsoft Corporation.<br />
IBM, DB2, DB2 Universal Database, System ads, System i5,<br />
System p, System p5, System x, System z, System z10, System<br />
z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM,<br />
z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel<br />
Enterprise Server, PowerVM, Power Architecture, POWER6+,<br />
POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC,<br />
BatchPipes, BladeCenter, System Storage, GPFS, HACMP,<br />
RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex,<br />
MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and<br />
Informix are trademarks or registered trademarks of IBM<br />
Corporation.<br />
Linux is the registered trademark of Linus Torvalds in the U.S. and<br />
other countries.<br />
Adobe, the Adobe logo, Acrobat, PostScript, and Reader are<br />
either trademarks or registered trademarks of Adobe Systems<br />
Incorporated in the United States and/or other countries.<br />
Oracle is a registered trademark of Oracle Corporation.<br />
UNIX, X/Open, OSF/1, and Motif are registered trademarks of the<br />
Open Group.<br />
Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame,<br />
VideoFrame, and MultiWin are trademarks or registered<br />
trademarks of Citrix Systems, Inc.<br />
HTML, XML, XHTML and W3C are trademarks or registered<br />
trademarks of W3C ® , World Wide Web Consortium,<br />
Massachusetts Institute of Technology.<br />
Java is a registered trademark of Sun Microsystems, Inc.<br />
JavaScript is a registered trademark of Sun Microsystems, Inc.,<br />
used under license for technology invented and implemented by<br />
Netscape.<br />
<strong>SAP</strong>, R/3, xApps, xApp, <strong>SAP</strong> NetWeaver, Duet, PartnerEdge,<br />
ByDesign, <strong>SAP</strong> Business ByDesign, and other <strong>SAP</strong> products and<br />
services mentioned herein as well as their respective logos are<br />
trademarks or registered trademarks of <strong>SAP</strong> AG in Germany and<br />
in several other countries all over the world. All other product and<br />
service names mentioned are the trademarks of their respective<br />
companies. Data contained in this document serves informational<br />
purposes only. National product specifications may vary.<br />
These materials are subject to change without notice. These<br />
materials are provided by <strong>SAP</strong> AG and its affiliated companies<br />
("<strong>SAP</strong> Group") for informational purposes only, without<br />
representation or warranty of any kind, and <strong>SAP</strong> Group shall not<br />
be liable for errors or omissions with respect to the materials. The<br />
only warranties for <strong>SAP</strong> Group products and services are those<br />
that are set forth in the express warranty statements<br />
accompanying such products and services, if any. Nothing herein<br />
should be construed as constituting an additional warranty.