SAP Predictive Service User Guide

Developer Guide PUBLIC
2018-02-14
SAP Predictive Service User Guide

Content
1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 What's New. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 About the Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.1 Environment Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 Configuration Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1 Enable and Deploy the Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Install SAP Predictive Service Engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
4.3 Create the Technical Database User. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4 Bind the Data Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
4.5 Assign Roles to Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.6 Start the Service and Check the Binding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5 Business Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.1 Service Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.2 Architecture Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
5.3 Synchronous Mode Versus Asynchronous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.4 Use the Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.5 REST API Quick Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Clustering APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Dataset APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Forecasts APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Key Influencers APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Outliers APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Recommendation APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Scoring Equation APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
What If APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Job Response Body Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.6 Usage Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Creating Clusters with Either High or Low Target Rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.7 Error Messages Explained. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
General Service Parameter Error Messages (EXX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Database Error Messages (EDB). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Dataset Service Error Messages (EDS). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Job Access Error Messages (EJB). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Modeling Parameter Error Messages (EMO). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

2 PUBLIC Content
6 Predictive Analytics Integrator Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.1 Service Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
6.2 How the Service Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
About Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
About Validation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
About Model Activation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
6.3 OData REST API Quick Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Entity Data Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Catalog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Predictive Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Model Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.4 Usage Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Create, Train, and Apply. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Create, Train, and Apply (Deep Insert). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.5 Dealing with Complex Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
7 Data Protection and Privacy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

7.1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
7.2 Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
7.3 Read-Access Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.4 Information Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.5 Erasure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.6 Change Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.7 User Consent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
8 Datasets Available for SAP API Business Hub. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
9 Archive - Release Notes for SAP Predictive Service 2017. . . . . . . . . . . . . . . . . . . . . . . . . . . . .166

Content PUBLIC 3
1 Overview
The SAP Predictive Service User Guide is your documentation reference for learning how to access and
consume Machine Learning services leveraged by the SAP Cloud Platform.
Feature Scope Description
Feature Scope Description
The SAP Predictive service
The SAP Predictive service is a service available on the SAP Cloud Platform for enabling applications with
predictive capabilities. Using the service, an application can analyze the data stored in an SAP HANA instance
to get insights and make predictions.
The SAP Predictive service offers two collections of RESTful web services that you deploy on the platform as
one application:
● Business Services
They allow to get insights from data to be used by business analysts. Each service answers a specific
business question and therefore returns a specific type of insight.
● Predictive Analytics Integrator Services
They allow non-predictive cloud applications to easily integrate and consume predictive models. These
services enable the productive utilization of predictive models within the context of real-life business
processes.
You deploy this application on the instance of the SAP Cloud Platform of your company or customer before
using it.
Audience
Are you a business analyst?
You are able to understand business questions and you explore your data in search of new insights. Learn more
about the services in Business Service Description [page 18] to find which insights the predictive service can
provide.
Are you an administrator?
You know the SAP Cloud Platform cockpit and how to deploy the services on the platform instance. You assign
role to future users of the service. You create the technical database user and bind the service to the database
instance. See Configuration Tasks [page 13].

4 PUBLIC Overview
Are you a developer?
You address end-user needs identified by the business user. You develop the cloud application by using the
service that your cloud administrator has deployed. You know the concept of REST architecture style and you
are able to develop cloud applications based on REST APIs using Java or HTML5. You also know the OData 2.0
specification and are able to understand the entity model that supports the Predictive Analytics Integrator
services. REST APIs require a minimum amount of programming. See the REST API Quick Reference [page
25] for the Business Services and the OData REST API Quick Reference [page 103] for the Predictive
Analytics Integrator Services.
Are you a data scientist?
You have programming and data mining skills and you are able to help the developer to implement model
management tasks. See the OData REST API Quick Reference [page 103].
Learn More
This guide describes the services available in this release and how to install and deploy them on the instance.
The following table describes other information available for you to learn more about the predictive service and
the underlying Automated Analytics concepts.
Information Description
Automated Analytic User Guides and Scenarios on the SAP The SAP Predictive Analytics user guide for classification,
Help Portal, section User Guides and Scenarios regression, segmentation, and clustering scenarios. This
guide contains additional information about variables and
how to use them.
SAP HANA Automated Predictive Library Reference Guide on The reference for SAP HANA APL. This provides information
the SAP Help Portal, section Development on the predictive business functions such as forecast, key in
fluencers, and scoring equation.
Introducing SAP Predictive service A set of videos that show you how to get started with the
predictive service APIs, how they work and how to use them.
SAP API Business Hub - Business Services Explore, test, and consume the Business Services through
the SAP API Business Hub.
SAP API Business Hub - Predictive Analytics Integrator Serv Explore, test, and consume the Predictive Analytics Integra
ices tor Services through the SAP API Business Hub.
Tutorial Catalog Learn by doing on the SAP Cloud Platform developer center.

Overview PUBLIC 5
2 What's New
The following table provides information about what is new and what has changed since the last release.
Version Date Type of Description

Change
Not applicable 2018-02-15 New Documentation
A section about data protection and privacy has been added. See
Data Protection and Privacy [page 160].
Not applicable 2018-01-22 New Documentation
Release notes are now archived into the user guide. See Archive - Re
lease Notes for SAP Predictive Service 2017 [page 166].
Not applicable 2017-11-21 New The Feature Scope Description document is released. See Feature
Scope Description.
2.03 2017-10-20 Enhancement Documentation
The interactive API documentation has moved to SAP API Business

Hub. See SAP API Business Hub - Business Services .
2.02 2017-9-25 Announcement The service name is now SAP Predictive service.
Fix Documentation
The configuration tasks have been updated. See Configuration Tasks

[page 13].
Enhancement Documentation
The version numbers of the predictive service have been added to the
What's New.
2.01 2017-7-26 Enhancement All services
When creating a job, the input parameter of the response is now

formatted as a JSON object instead of a string. See Job Response
Body Parameters [page 86].
Enhancement Key Influencers
The service now allows end-users to get the variables that are corre
lated to each other, with their coefficient of correlation. See Key Influ
encers APIs [page 52].
Enhancement Error codes and messages
EXX121 is a new message related to incompatibility between input pa

rameters. See General Service Parameter Error Messages (EXX)
[page 97].

6 PUBLIC What's New
Change
An important note has been added to the Clustering APIs documen

tation to explain the link between the view export method and the
modelSQLExportEnabled input parameter. See Clustering APIs
[page 26].
Fix Documentation
A correction has been made to the data source binding procedure.

Only <default> can be used as data source name. See Bind the Data
Source [page 15].
2.00 2017-6-19 New The new collection of services Predictive Analytics Integrator Serv
ices is available to add model management tasks to your application.
See Service Description [page 101].
1.14 2017-6-6 Enhancement Clustering
The service now allows end-users to specify the distance used to

measure the proximity of two data points. This is enabled through the
distance input parameter. See Clustering APIs [page 26].
Enhancement Forecasts
The service now allows end-users to:
● Specify the maximum lag to consider when forecasts are com

puted. This is enabled through the maxLag input parameter.
● Get the MAPE indicator for each horizon. This is output in the
mapePerHorizon parameter under modelPerformance.
See Forecasts APIs [page 45].
1.13 2017-5-22 Enhancement Datasets
The service now allows end-users to specify the schema and the ta
ble of the dataset in SAP HANA separately in the request. This is ena
bled through the location input parameter. hanaURL has been
deprecated. See Dataset APIs [page 32].
1.12 2017-5-9 Enhancement Scoring Equation
The service now allows application users to choose the type of output
generated by the scoring equation (predicted value or probability).
This is enabled through the predictionOutputType input pa
rameter. See Scoring Equation APIs [page 77].
1.11 2017-4-24 Enhancement All services
The variableDescription parameter has been deprecated

from the request body of the APIs. From now on, application users
must use the Dataset APIs to specify the variable descriptions (Reg
ister an SAP HANA Table as Dataset [page 33]) or to modify them
(Modify the Variable Description [page 42]).

What's New PUBLIC 7
Change
Enhancement Outliers and Scoring Equation
These services now allow application users to set the key of the target
variable through the TargetKey input parameter. See Outliers APIs
[page 58] and Scoring Equation APIs [page 77].
The documentation now specifies that referenceDate must fol

low the ISO 8601 format in the Forecasts API request. See Forecasts
APIs [page 45].
1.10 2017-4-10 New Clustering
A new Clustering service is available and provides a set of APIs that

allow you to segment an input dataset into clusters and to get seg
mentation results into an SAP HANA database table or view. See
Clustering APIs [page 26].
Enhancement Outliers
The service now allows application users to enable autoselection of

variables through the autoSelection input parameter. See Outli
ers APIs [page 58].
New Documentation
A first usage scenario has been added to the documentation. It de

scribes an end-to end clustering process. See Creating Clusters with
Either High or Low Target Rate [page 87].
1.9 2017-3-13 Enhancement Forecasts
● The service now allows application users to specify the modeling

technique used to generate forecasts: the default Automated
Analytics technique, the exponential smoothing, or the linear re
gression. This is enabled through the forecastMethod re
quest parameter of the APIs [POST] /api/analytics/
forecast/sync and [POST] /api/analytics/
forecast.
● The service also allows application users to specify the cycle
length in the case of the smoothing technique. This is enabled
through the smoothingCycleLength request parameter of
the same APIs.
Enhancement Dataset
The service now allows application users to specify if a variable col

umn is a component of the primary key.
New SAP API Business Hub
You can now explore, test, and consume the predictive service
through the SAP API Business Hub .

8 PUBLIC What's New
Change
New Documentation
A link to videos has been added to the Overview [page 4]. These vid
eos explain how to deploy the predictive service and how it works.
1.8 2017-2-13 New SAP HANA
The predictive service supports SAP HANA 1.0 SPS12.
Enhancement Dataset
The service now allows application users to modify the value types of
the variables. This is enabled through the new API [POST] /api/
analytics/dataset/<datasetID>/variables/update.
Enhancement Error codes and messages
● HTTP code of EDS101 has changed from 500 to 400.

● EDS111 is a new message related to blank characters not allowed
in dataset column names.
1.7 2017-1-16 New SAP HANA APL
The predictive service supports SAP HANA APL 3.1.
● The service now returns the past data with both predicted and
real values of each data point. This is enabled through the
numberOfPastValuesInOutput request parameter.
● The service now returns the definition of the trend, cycles, and
fluctuation features found in the data and used by the underlying
time series model to generate forecasts. This information is
available through modelInformation in the output.
Enhancement Dataset
When registering a dataset, you can now provide the description of

the variables contained in the dataset. The specified description is
used whenever the associated dataset is used with the predictive
service.
New Error codes and messages
EDS106 to EDS110 are new messages related to errors in the list of

variables provided in the dataset service request.
New Documentation
● An architecture diagram has been added, see Architecture Over

view [page 20]
● Procedures to assign roles, to create a DB user and to bind the
data source have been detailed.
● Code examples have been added, see Use the Service [page
21]

What's New PUBLIC 9
Change
1.6 2016-12-2 New Recommendation
A new Recommendation service is available and provides a set of

APIs that allow you to do the following:
● Creating and managing a recommendation model

● Applying a recommendation model to generate recommenda
tions from a user's purchase history or simply the contents of
the user's cart
● Using a recommendation model to generate recommendations
for a group of users
● Estimating the costs of the creation of a recommendation model
before actually creating it
Enhancement Datasets
● Unregistering a dataset removes the registration data from the

database.
● Deleting a job removes the job data from the database.
New/Enhance Error codes and messages

ment
● HTTP codes of EXX100, EXX108, and EXX110 have changed from
400 to 500.
● HTTP code of EXX112 has changed from 400 to 403.
● EXX109 error message has changed.
● Error messages from EXX113 to EXX120 are new. EXX114 error
message replaces EAA101 and EFC110. EXX15 error message re
places EWI101.
● EDA messages are obsolete and no more documented.
● EDB001 to EDB003 are new messages related to database er
rors.
● EDS101 to ESD105 are new messages related to dataset service
errors and replace EDS3100 and EDS4100.
1.5 2016-10-24 Enhancement Datasets
Variable statistics are now computed on the fly, that's why:
● Registering datasets takes less time.

● Variable statistics reflect the current state of the dataset.
The response call to getting forecasts now provides the

maximumConfidentHorizon parameter, which specifies the
maximum horizon, for which the performance indicators are reliable.
New Forecasts
Documentation: a table MAPE/Quality Rating has been added.
Enhancement Outliers
The service returns all outliers if numberOfOutliers value is 0.

10 PUBLIC What's New
3 About the Service
The SAP Predictive service offers two sets of web services used to perform predictive analysis on data
resources stored in the SAP HANA database of the cloud.
The predictive service takes charge of the complexity of developing services directly on the predictive model
engine. Web services are easy to understand, and provide a simple programming paradigm, which is adapted
for Web applications on the cloud. The predictive service supports CRUD (Create, Read, Update, Delete)
operations on data over HTTPS, sending requests and receiving responses in JSON format only.
You deploy these two sets as an application on the SAP Cloud Platform instance before using them. A schema
is created on the database to store the data used by the service, such as the service call history and the job
results. The data resources are datasets stored in SAP HANA database tables. They must be registered in the
database schema, which can be different from the one used by the service.
Business Services
These services are REST APIs and allow you to expose the predictive analytics functionalities in the application
you develop.
On each call to a service, a predictive model is built from the dataset and a target by using SAP HANA APL
(included in SAP Predictive service engine). The results returned by the service are retrieved from the
predictive model.
The predictive service provides synchronous and asynchronous predictive model execution. For models that
require a long processing time, asynchronous execution allows a better user experience.
One service returns one type of insight. Each service operates the data mining process. Each service allows you
to finetune the creation of the model, for example by using the variable autoselection feature, by correcting
the variable descriptions, or by ignoring columns that contain unnecessary information, such as column
identifiers.
See Service Description [page 18].
Predictive Analytics Integrator Services
These services are OData REST APIs and allow you to integrate predictive models for consumption in the
application you develop. The OData 2.0 specification is used to represent data objects that describe and
reference the models available.
A series of calls to the services is necessary to train and apply any predictive model stored in the back-end
system. These model management tasks can be fully integrated with the application's own user experience
and workflow.
See OData REST API Quick Reference [page 103].

About the Service PUBLIC 11
Caution
The Predictive Analytics Integrator Services are not available on trial accounts.
3.1 Environment Requirements
To work with the predictive service, you require the following:
● An access to an instance of the SAP Cloud Platform

● The latest available version of SAP Predictive service engine installed on this instance
● The service application deployed on this instance

12 PUBLIC About the Service
4 Configuration Tasks
Before using the predictive service, make sure you complete the following tasks.
Prerequisites
● You have access to an SAP Cloud Platform global account.

● You are an administrator within the account.
● You are logged into your subaccount.
Remember
You need a productive SAP HANA instance to use the service. Your SAP HANA instance requires at least 64
GB of memory.
1. Enable and Deploy the Service [page 13]

2. Install SAP Predictive Service Engine [page 14]
3. Create the Technical Database User [page 15]
4. Bind the Data Source [page 15]
5. Assign Roles to Users [page 16]
6. Start the Service and Check the Binding [page 17]
4.1 Enable and Deploy the Service
1. Click Services in the left menu of your SAP Cloud Platform cockpit.
The Predictive Service tile appears.

2. Choose Predictive Service.
3. The service should be enabled. If the service is not enabled, then click Enable.
4. Check that you have the AA-Admin role and assign it to yourself if needed.
a. Choose Configure Predictive Service Roles .

b. Assign the AA-Admin role to yourself and to identified users.
If you have enabled the service, this role has automatically been assigned to you.
c. Go back to Predictive Service page.
5. Click Go to Service.

Configuration Tasks PUBLIC 13
Note
If you click Documentation, this user guide appears in a new window.
The Predictive Service Cockpit window appears.

6. Choose the Deploy the predictive service tile.
7. Enter your subaccount password and click Deploy.
You can also change the Compute Unit setting to assign more CPU/RAM to the services.
A link to the dashboard of the service appears.
The aac4paservices Java application is deployed and stopped.
You must install SAP Predictive service engine on the SAP HANA instance.
Task overview: Configuration Tasks [page 13]
Next task: Install SAP Predictive Service Engine [page 14]
4.2 Install SAP Predictive Service Engine
● The application is deployed and stopped.

● The SAP HANA instance is running.
1. Click SAP HANA / SAP ASE Database Systems in the left menu and the name of your instance.
2. Click Install components.
The Install Components window appears.

3. In the Selection Solution dropdown list, choose SAP Predictive service engine.
4. In the Target Version column, choose the only target version available for your version of SAP HANA.
Review and confirm before applying the installation is checked by default. If you uncheck it, click Install to
install SAP Predictive service engine directly; otherwise, click Continue.
5. After the component is prepared for installation, click Install.
The configuration step begins automatically.

6. After Installation of components verified is checked successfully, click Finish.
SAP Predictive service engine is installed on your instance.
You must create the technical database user, which is used to bind the SAP HANA instance to the application.
Previous task: Enable and Deploy the Service [page 13]
Next task: Create the Technical Database User [page 15]

14 PUBLIC Configuration Tasks
4.3 Create the Technical Database User
● The SAP HANA instance is running.
● SAP Predictive service engine has been installed on the SAP HANA instance.
● You have created your database user to connect to the SAP HANA instance. See Creating a Database
Administrator User for more information.
● Your database user has permissions to create users and grant them rights.
You create a technical database user that will be used to bind the SAP HANA instance to the application and
grant it the necessary rights to use the service.
1. Connect to your productive SAP HANA instance using an SAP HANA administration tool such as the SAP
HANA cockpit or SAP HANA Studio.
2. Create a new database user.
This database user is used as a technical database user by the service.
Remember
You cannot use your own database user as a technical database user for the service. You must create a
new database user.
3. Grant the technical database user the following rights:
○ sap.pa.apl.base.roles::APL_EXECUTE for the use of Business Services

○ sap.hana.pai::ExecutePAI for the use of Predictive Analytics Integrator Services
4. Grant the technical database user the following rights to make the service access the database schemas:
○ SELECT rights to the schema that contains the datasets that the service will analyze
○ CREATE ANY and INSERT rights to the schema into which the service will write analysis results.
The technical database user has been created. It is granted all necessary rights for using the service.
Bind the SAP HANA instance to the application using the technical database user.
Previous task: Install SAP Predictive Service Engine [page 14]
Next task: Bind the Data Source [page 15]
4.4 Bind the Data Source

● The technical database user has been created.
Create a data source binding for the application against the SAP HANA instance. You connect the predictive
service to your SAP HANA instance with the technical database user.

Note
For more information about binding, see the "By application" procedure in Bind Databases to Applications.
1. Go to the aac4paservices application dashboard.
2. Click Configuration Data Source Bindings .

3. Click New Binding.
4. Enter the user name and password of the technical database user.
You must keep the default proposed <default> data source name.
Caution
The database user name you set in Custom Logon must be the new technical database user name. It
must not be your own database user name.
The application is bound to the SAP HANA instance.
Grant users rights to use the service.
Previous task: Create the Technical Database User [page 15]
Next task: Assign Roles to Users [page 16]
4.5 Assign Roles to Users
The application is deployed and stopped.
You assign the following roles:
● The C4PA-User role enables a user to use the service.

● The C4PA-Admin role enables a user to have access to the administration interface of the service.
See the "Assign Users or Groups to the Roles" section in Managing Roles.
1. Go to the aac4paservices application dashboard.

2. Click Roles in the left menu.
3. Select the C4PA-User role.
4. To assign a new user or group to this role, choose Assign either in the Individual Users or Groups section.
5. Enter the user or group name.
6. Select the C4PA-Admin role and repeat steps 6 and 7.
Users with the C4PA-User role can call the service after the application is started. Users with the C4PA-Admin
role can access the administration interface of the service after the service is started.
Start the service and check that everything is OK.

16 PUBLIC Configuration Tasks
Previous task: Bind the Data Source [page 15]
Next task: Start the Service and Check the Binding [page 17]
4.6 Start the Service and Check the Binding
You must have the C4PA_Admin role.
1. Go to the Overview page of the application dashboard and click Start to start the aac4paservices
application.
2. Once the application is started, check whether the binding is correct:
a. Click the application URL on the Overview page.
b. Choose the Administration tile and make sure that the status is OK.
c. Choose the Binding tile to see the binding details.
The predictive service is correctly configured.
Previous task: Assign Roles to Users [page 16]

5 Business Services
5.1 Service Description
The Business Services allow you to perform predictive analysis operations on a dataset.
The following tables show the services available in this release.
Table 1: Business Services

Service Description Benefits
Clustering ● Segments a population into homogeneous Using this service, an end user can for example:
clusters ● Group together similar customers
● Sends segmentation results into the desired ● Identify emerging customer profiles
SAP HANA table or view for visualization pur
● Identify interesting clusters they can focus on
pose
● Creates clusters driven by a target indicator,
which mean members of a cluster are similar
according to some business question (super
vised clustering)
Forecasts Generates forecasts for a time series Using this service, an end user can predict the next
values of a time series from a reference date.
Key Influencers Returns the variables which have an influence on Using this service, an end user can for example:
a specified target ordered by decreasing contri
● Have a better understanding of the profile of the
bution
targeted population
● Identify the drivers of success and learn how to
improve performances
● Have leads on potential causes of a targeted
event
Outliers Identifies the odd profiles of a dataset whose tar Using this service, an end user can detect for exam
get indicator is significantly different from what is ple:
expected
● Attributes that were not filled correctly
● Potential frauds
● Unconventional profiles

18 PUBLIC Business Services
Service Description Benefits
Recommenda Creates and uses a recommendation model to Using this service, an end user can do the following:
tion generate a list of items to suggest to users.
● Create a model based on a dataset restricted to
a specific time period
● Generate recommendations for a given user or
group of users
● Generate recommendations from a basket of
items that are not purchased yet
● Update recommendations at the same time as
the transaction history is updated
● Estimate the cost and performance of the model
before its creation
● Iterate to find modeling settings with best bal
ance between costs and capabilities
Scoring Equa Exports the scoring equation of a predictive Using this service, an end user can for example:
tion model
● Integrate the predictive model within an applica
tion
● Use the predictive model as many times as
wanted
● Apply the predictive model on new data on the
fly
What If Simulates a planned action and returns the signif Using this service, an end user can for example:
icant deviations compared to what is expected
● Identify unexpected consequences of an action,
such as additional costs, workload reestimation,
and changes in a process
● Gain potential insights by investigating and vali
dating the hidden relationship between the plan
ned action and its consequences
Table 2: Utility Service

Service Description
Dataset Provides a series of functions to manage datasets:
● Registers a dataset stored in another SAP HANA schema for further use with
the predictive service
● Retrieves dataset and variable information

Business Services PUBLIC 19
5.2 Architecture Overview
The SAP Cloud Platform application you develop consumes the predictive service deployed on your
subaccount.
User data and service metadata are stored in your SAP HANA instance. User data are datasets owned by the
end user and service metadata are service call history and job results (Predictive Service Repository).
It is possible to create a dataset that refers to a table/view in a different schema from the Predictive Service
Repository, as long as schemas are stored in the same SAP HANA instance.
1 The SAP Cloud Platform application you have developed reads/writes user data.
2 The predictive service reads the user data to create dataset objects.
3 SAP HANA APL reads user data for all service processing and writes to it for the Recommendation and Clustering serv
ices.
4 The predictive service reads/writes service metadata to the Predictive Service Repository.
The SAP Cloud Platform application also relies on the SAP Cloud Platform services such as administration,
monitoring, and authentication services.

5.3 Synchronous Mode Versus Asynchronous Mode
An end user can call a service using either a synchronous or asynchronous mode.
The synchronous mode is convenient to test services on small datasets as you receive results in one call. It may
not be appropriate to larger datasets and if it takes too long to build the model. Therefore, the end user can use
the service in asynchronous mode to save time.
In asynchronous mode, the service first creates a job whose ID is returned to the end user. The job then
proceeds the same way as in the synchronous mode, except that the job results are saved for a certain amount
of time. Instead of waiting for the results, the end user can retrieve the job results later, after making sure they
are available.
See an example in Use the Service [page 21].
5.4 Use the Service
The predictive service is deployed on an instance of the SAP Cloud Platform.
You can use any supported programming language to develop your application in the cloud, for example Java
or HTML5/JavaScript. See the SAP Cloud Platform developer documentation.
You are developing an application that will allow an end user to perform predictive analysis from their own SAP
HANA data.
1. Use the following Dataset Service API to register an existing SAP HANA table as a dataset: POST/api/
analytics/dataset/sync
2. Call the service either in synchronous or in asynchronous mode:
The examples are given for the Key Influencer service.
Option Description
Synchronous mode 1. Call the service by using the dataset ID and other parameters.
POST /api/analytics/keyinfluencer/sync
Asynchronous mode 1. Create the job and retrieve its ID.

POST /api/analytics/keyinfluencer
2. Retrieve the job status using its ID.
GET /api/analytics/keyinfluencer/<jobID>/status
3. Retrieve the results of the job in JSON format.
GET /api/analytics/keyinfluencer/<jobID>
Example
You are developing an HTML5 application on the SAP Cloud Platform to demonstrate the Key Infuencer APIs
usage. Your goal is to create buttons that trigger API calls and to make the application display dataset
information and final results. You use JavaScript to write server requests with the $.ajax() jQuery AJAX

function. You embed your code.js script and its requests into an HTML5 page. You create the following
variables to represent buttons that trigger API calls and place them into your page:
● get_dataset to register a customer dataset

● bKeyInfluencer to create the job and retrieve its ID
● bGetStatus to retrieve the job status
● bkeyInfluencerResult to retrieve and display the results of the final call
1. Write a button to register the dataset and to display the dataset:
var get_dataset = new sap.ui.commons.Button({

text : "Create Dataset from PS_DATA/SMALL_SALES",
style: sap.ui.commons.ButtonStyle.Emph,
press : function() {
$.ajax({
type : "POST",
contentType : "application/json",
url : root + "/api/analytics/dataset/sync",
dataType : 'json',
data: JSON.stringify({"hanaURL": "PS_DATA/SMALL_SALES"}),
success : function(data, status, request) {
$('#datasetID').val(data.ID);
gDataID = data.ID;
displayVariables(data.ID);
},
...
});
}
});
where the displayVariables function triggers the GET /api/analytics/dataset call to retrieve
the dataset information:
function displayVariables(id) {
$.ajax({
type : "GET",
url : root + "/api/analytics/dataset/" + id,
dataType : 'json',
var i = 0;
var rowCount = 0;
var oItem;
ddlb_variables.destroyItems();
for (i = 0; i < data.variables.length; i++) {
addRowInTable("variablesTable", data.variables[i].name,
data.variables[i].value);
oItem = new sap.ui.core.ListItem();
oItem.setText(data.variables[i].name);
ddlb_variables.addItem(oItem);
}
ddlb_variables.setValue(data.variables[data.variables.length -
1].name);
gTarget = data.variables[data.variables.length - 1].name;
ddlb_variables.attachChange(function(){
$('#target').html(ddlb_variables.getValue());
gTarget = ddlb_variables.getValue();
});
ddlb_variables.placeAt("ddlb_ChooseTarget");
$('#target').html(ddlb_variables.getValue());
},
...
}

});
}
2. Write a button that creates the API job:
var bKeyInfluencer = new sap.ui.commons.Button({

text : "Find Key Influencers",
$.ajax({
type : "POST",
url : root + "/api/analytics/keyinfluencer",
dataType : 'json',
data: JSON.stringify({"datasetID": gDataID, "targetColumn":
gTarget}),
gJobID = data.ID;
var res = 'Job ID: ' + data.ID + ' Status: ' + data.status
+ ' type: ' + data.type;
$('#status').html(res);
},
...
});
}
});
3. Write a button that triggers the following function to display the job result:
var bGetStatus = new sap.ui.commons.Button({

text : "Get Status of job",
$.ajax({
type : "GET",
url : root + "/api/analytics/keyinfluencer/" + gJobID + "/
status",
dataType : 'json',
var res = 'id: ' + data.ID + ' status: ' + data.status + '
type: ' + data.type;
$('#status').html(res).css("background-color", "");
},
...
}
});
}
});
4. Write a button that triggers the following function to display the results:
var bKeyInfluencerResult = new sap.ui.commons.Button({

text : "Display Key Influencers:",
...
$.ajax({
type : "GET",
url : root + "/api/analytics/keyinfluencer/" + gJobID,
dataType : 'json',
// Get KI and KR
$('#tKI').html(data.modelPerformance.predictivePower);
$('#tKR').html(data.modelPerformance.predictionConfidence);
var contrib = 0;
for (var i = 0; i < data.influencers.length; i++) {
contrib = data.influencers[i].contribution*100;

addRowInTable("keyInfluencers",
data.influencers[i].variable, contrib.toFixed(4));
}
},
...
});
}
});
5. Write an HTML5 page:

To embed your script :
<head>
<title>Your demo application</title>
<script id="sap-ui-bootstrap"
src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js"
data-sap-ui-theme="sap_bluecrystal"
data-sap-ui-libs="sap.ui.commons"></script>
<script type="text/javascript" src="code.js"></script>
</head>
To display the dataset information (name, rank, type):
<table id="param">
<tr>
<th><div id="get_dataset"></div></th>
<th>Dataset ID</th>
<th><input type="text" id="datasetID"/></th>
<th><div id="get_variables"></div></th>
</tr>
<tr>
<th colspan="4"><div id="out_param"></div></th>
</tr>
</table>
<table id="variablesTable">
<tr>
<th>Rank</th>
<th>Name</th>
<th>Type</th>
</tr>
</table>
To display the target variable, the job status and the results:
<table id="param">
<tr>
<td>Choose target</td>
<td><div id="ddlb_ChooseTarget"></div></td>
<td><div id="target"></div></td>
</tr>
<tr>
<td><div id="bKeyInfluencer"></div></td>
<td><div id="bGetStatus"></div></td>
<td><div id="status"></div></td>
</tr>
<tr>
<td><div id="bKeyInfluencerResult"></div></td>
<td>Job ID </td>
<td><input type="text" id="jobID"/></td>
</tr>
<tr>
<td>Predictive Power (KI)</td>
<td><div id="tKI"></div></td>
<td>Robustness (KR)</td>
<td><div id="tKR"></div></td>
</tr>

</table>
<table id="keyInfluencers">
<tr>
<th align="center">Rank</th>
<th align="left">Name</th>
<th align="right">Contribution (%)</th>
</tr>
</table>
5.5 REST API Quick Reference
An overview of the SAP Predictive service APIs provided as web services in the cloud.
Each API reference provides the following information:
● What the API does

● URLs of the HTTP requests
● Description of the request path, query, and body parameters
● Description of the response content
Test these APIs directly in the SAP API Business Hub with the sample datasets described in Datasets
Available for SAP API Business Hub [page 164].
Note
The base URL to use with the REST APIs depends on the instance where you have deployed the predictive
service.
Related Information
Clustering APIs [page 26]

Dataset APIs [page 32]
Forecasts APIs [page 45]
Key Influencers APIs [page 52]
Outliers APIs [page 58]
Recommendation APIs [page 62]
Scoring Equation APIs [page 77]
What If APIs [page 81]

5.5.1 Clustering APIs
The Clustering service analyzes a dataset and segments it into homogeneous clusters.
The service groups similar entities of a dataset into clusters. The resulting clustering information is then
exported to the SAP HANA database. The clusters IDs can be written to a database table or view.
The end user must specify the numbers of clusters that the service should return, expressed as a range. The
service returns the best clustering whose number of clusters is in the range.
The user must also set the name and schema of the table or view where the results are stored. Optionally, they
can choose the variables from which the clustering can be defined and set a target variable in case of
supervised clustering.
The service returns information on the clusters and stores results into the requested table. It also provides
model performance information in case of supervised clustering.
APIs
Table 3: Synchronous Mode

Action HTTP Method URI Request Body Response Body
Segmenting the da POST /api/analytics/ input [page 27] output [page 30]
taset into clusters clustering/sync
Table 4: Asynchronous Mode

Creating a job POST /api/analytics/ input [page 27] output [page 86]
clustering
Getting the job sta GET /api/analytics/ None output [page 86]
tus clustering/<jobID>/
status
Getting the cluster GET /api/analytics/ None output [page 30]

ing information and clustering/<jobID>
results
Deleting the job DELETE /api/analytics/ None None

clustering/<jobID>
Request Path Parameters
Parameter Required Type Description
<jobID> Yes Integer The job identifier that you get by creating a job first

Request Query Parameters
None
5.5.1.1 Request Body Parameters
The list of input parameters for the synchronous mode API and the asynchronous job creation API of the
Clustering service.
{
"datasetID",
"numberOfClusters",
"exportSettings" : {
"method",
"destination" : {
"schema",
"table",
"overwrite",
},
"clusterIDColumn"
},
"selectedVariables",
"skippedVariables",
"target" : {
"column",
"value"
},
"modelSQLExportEnabled",
"distance"
}
Table 5: Dataset Parameters

Parameter Required Type Description Default
datasetID Yes Integer The identifier of a dataset that has been registered N/A
in the schema.
Table 6: Service Parameters

numberOfCl Yes Array of inte The minimum and maximum numbers of clusters N/A
usters gers requested, specified as a 2-value array.
The minimum is the first value, the maximum is the

second one. For example: [1,5].
Note
A clustering model is created for each number
of clusters in the range, so that the service can
select the best. Therefore,
numberOfClusters could hinder the service
performance if a wide range is specified.

exportSett Yes Object The settings that configure how the segmentation N/A
ings [page results are returned to the end user.
28]
Table 7: Export Settings

method No String How segmentations results are returned. table
The possible values are:
● table
The service exports the results into an SAP
HANA database table. If a primary key has
been specified for the input dataset, the desti
nation table only contains the primary key
component columns and the column that con
tains the cluster IDs. Else, all columns from the
input dataset are copied to the table, which
could hinder the service performance.
● view
The service exports the results in the form of a
dynamic view created on top of the dataset
specified in the request. As the clustering defi
nition is integrated into the view, new data
points in the table can automatically be as
signed a cluster ID.
Remember
● The view method requires the clustering
models to be defined as SQL queries, which
means modelSQLExportEnabled
must be set to true if you choose this ex
port method.
● Both methods generate different segmen
tation results, because
modelSQLExportEnabled is activated
by default in the view case, but not in the
table case.
destinatio Yes Object The destination where the segmentation results are
n [page 29] stored.
clusterIDC No String The name of the column that contains the cluster CLUSTER_ID
olumn IDs in the destination table or view.

Table 8: Destination
schema Yes String The name of the schema where the destination ta N/A
ble or view is created.
The predictive service DB User must have CREATE

ANY rights on this schema.
table Yes String The name of the destination table or view that is N/A
created.
overwrite No Boolean Indicates that the destination table or view is drop false
ped and recreated if it exists.
By default, the table or view is not overwritten.
Table 9: Modeling Parameters

selectedVa No Array of strings The list of variables used to do the clustering. All variables are
riables selected.
skippedVar No Array of strings The list of variables that should not be included in No variable is
iables the analysis. excluded.
If selectedVariables is specified,
skippedVariables is ignored.
variableDe Array of objects The tuples are name and value pairs for the follow Null. The de
scription Cau ing parameters that describe the variable: scription stored
tion ● variable
with the data
set is used.
Deprecated ● storage
● value
● key
● missing
Note
Only variable, storage, and value must
be in the input. The other parameters can be
omitted.
target [page No Object The definition of the target in the case of super Null
30] vised clustering.
modelSQLEx No Boolean Indicates if the clustering model can be exported as false if the
portEnable an SQL query. method is
d table
This allows to export the clustering results as a
view. It must be set to true if you choose the view true if the
method ("method" : "view"). method is
view

distance No String The distance used to measure the proximity of two SystemDete
data points. rmined
Possible values are the following:
● LInf, Chessboard distance

● L1, City Block distance
● L2, Euclidean distance
● SystemDetermined: the system defines
the distance to be used according to the model
build settings
The current policy is to use LInf either in unsuper

vised mode or when the clusters SQL expressions
have been asked for
(modelSQLExportEnabled is set to true),
and L2 otherwise.
See Setting Up the Advanced Options in Automated

Analytics User Guides and Scenarios on the SAP
Help Portal.
Table 10: Target Settings

column Yes String The name of the target column in case of super N/A
vised clustering.
value No String The target value if the target column is binary. Null
If null, the targetKey will be the category with

the less frequency.
Note
This setting only applies to classification (binary
target) and is ignored in regression (continuous
target).
Related Information
5.5.1.2 Response Body Parameters
The list of output parameters for the synchronous and asynchronous APIs of the Clustering service.

"parameters" : {
...
},
"clustering" : {
"numberOfClusters",
"percentageOfUnassignedRecords",
"overlapRate"
},
"clusters" : [
{
"ID",
"name",
"frequency",
"targetMean"
}
],
"segmentationResults" : {
"schema",
"table"
},
"modelPerformance" : {
"qualityRating",
"confidenceIndicator",
"predictivePower",
"predictionConfidence"
}
}
Output Type Description
parameters [page Object The content of the request body.

27]
clustering [page Object Clustering information.

31]
clusters [page 31] Array of objects The list of clusters with their IDs and frequency.
segmentationRes Object The location of the segmentation results.

ults [page 32]
modelPerformanc Object Indicators on the quality of the results. Only provided in the case of su
e [page 32] pervised clustering.
Table 11: Clustering Information

numberOfCluster Integer The number of resulting clusters.

s
percentageOfUna Number The percentage of rows in the dataset that are not in any clusters.
ssignedRecords
overlapRate Number The percentage of rows in the dataset that are in multiple clusters.
Table 12: Clusters

ID Integer The cluster identifier.
name String The name of the cluster.
By default, a cluster will be named Cluster_ID.

frequency Number The size of the cluster as percentage of the number of rows in the data
set.
targetMean Number The average value of the target inside the cluster.
Only returned if a target variable has been defined in the request (super
vised clustering).
Table 13: Location of Segmentation Results

schema String The name of the schema where the segmentation results are stored
table String The name of the table or view where the segmentation results are stored
Table 14: Model Performance (supervised clustering only)

qualityRating Integer The model quality indicator in 0-5 range.
confidenceIndic Integer The model robustness indicator. 1 if the results are reliable, else 0.
ator
predictivePower Number The predictive power of the model that has generated the results.
predictiveConfi Number The prediction confidence of the model that has generated the results.
dence
Related Information
5.5.2 Dataset APIs
The Dataset services provide a series of features that manage datasets to be used with the predictive service.
These services:
● Register a dataset in the application

● Unregister a dataset
● Retrieve registered dataset information
● Retrieve information on a variable of a dataset
● Modify the description of the dataset variables

APIs
Action HTTP Method URI
Register an SAP HANA Table POST /api/analytics/dataset/sync

as Dataset [page 33]
Unregister a Dataset [page DELETE /api/analytics/dataset/<datasetID>

37]
Get Dataset Information [page GET /api/analytics/dataset/<datasetID>

37]
Get Variable Information [page GET /api/analytics/dataset/<datasetID>/variable/

39] <variablePosition>
Modify the Variable Descrip POST /api/analytics/dataset/<datasetID>/

tion [page 42] variables/update
Parameter Type Description
<datasetID> Integer The identifier of the registered dataset
<variablePosition> Integer The position of the variable in the dataset
5.5.2.1 Register an SAP HANA Table as Dataset
You can register an SAP HANA table as dataset.
By using this service, you register a dataset stored in an SAP HANA table into the application and assigns an ID
to it.
This service returns an error when:
● The application cannot access the dataset.

● There are inconsistencies between the specified variables and the ones retrieved from the dataset, for
example different storages. However, if the position of a variable specified in the request is invalid, the
service will replace the position with the correct one retrieved from the dataset and will return it in the
response.
Request
URI: /api/analytics/dataset/sync
HTTP Method: POST
Request Path Parameters: None

Request Query Parameters: None
Request Body Parameters
{
"location" : {
"schema",
"table"
},
"variables" : [
{
"position",
"name",
"storage",
"value",
"key"
},
{...},
...
]
}
hanaURL String The reference to the SAP HANA table that needs to
Caution
be registered:
Deprecated.
<schema_name>/<table_name>
SELECT rights are required to register a dataset.
This is only possible if the schema is stored in the

SAP HANA database used by the predictive serv
ice.
location Yes Object The location of the SAP HANA table or view that is
to be registered as dataset.
The table or view must be stored in the same SAP

HANA instance as the one used by the service.
SELECT rights on the specified schema must be

granted to the predictive service DB user.
variables No Array of objects The list of variables and their description in the da
taset.
If not specified, a guess is applied to determine the

variables.
Only name and value are mandatory.
Table 15: Location

schema No String The schema of the dataset in the SAP HANA data Predictive Serv
base ice Repository
schema
If not specified, the Predictive Service repository
schema is considered by default.

table Yes String The name of the table or view where the dataset is
stored
Table 16: Variables

position No Integer The position of the variable in the dataset. Null
If not specified, the position is retrieved from the

physical dataset table.
name Yes String The variable name N/A
storage No String The data type of the value stored in the variable: N/A
● integer: the variable contains integer values

● number: the variable contains decimal values
● string: the variable contains character
strings
● datetime: the variable contains dates and
timestamps
● date: the variable contains dates only
If not specified, the storage is retrieved from the

physical data type of the variable.
value Yes String The type of the value stored in the variable: Null
● continuous: numeric variable of which

mean or variance can be computed
● nominal: categorical variable that is the only
possible value for a string
● ordinal: discrete, relative variable where the
relative order is important
Note
Ordinal variables are currently considered as ei
ther continuous or nominal variables depending
on their storage type.
key No Integer A flag that indicates if the column is a component 0

of a primary key
● 0: the variable is not an identifier

● 1: the variable is part of the primary key
Response
{
"ID",
"name",
"location" : {

"schema",
"table"
},
"numberOfRows",
"numberOfColumns",
"variables" : [
{
"position",
"name",
"storage",
"value",
"key"
},
{...},
...
]
}
Table 17: Dataset Information

ID Integer The identifier of the dataset
name String The name of the dataset
location Object The location of the SAP HANA table or view where the dataset is stored,
with the following information:
● schema
● table
numberOfRows Integer The number of rows in the dataset
numberOfColumns Integer The number of columns in the dataset
variables Array of objects The list of variables in the dataset with the following information:
● position
● name
● storage
● value
● key
Example
Continuous vs Nominal vs Ordinal
The variable "salary" is a numerical variable, but in addition, is also a continuous variable. It may, for
instance, take on the following values: "$1,050", "$1,700", or "$1,750". The mean of these values may be
calculated.
The variable "zip code" is a nominal variable. The variable values ("10111", "20500", "90210", for example)
are clearly distinct, non-ranked categories, although they are represented by numbers. Binary variables are
considered nominal variables.
The variable "school grade" is an ordinal variable. Its values actually belong to definite categories and can be
sorted. This variable can be:
● Numerical, if its values range between "0" and "20"

● Textual, if its values are A, B, C, D, E, and F

5.5.2.2 Unregister a Dataset
You can unregister a dataset from the application.
This service unregisters the specified dataset from the application. Unregistering a dataset prevents further
use of this dataset with the predictive service. It does not remove the dataset content.
The service returns an error when the dataset does not exist.
Request
URI: /api/analytics/dataset/<datasetID>
HTTP Method:DELETE
None
None
Response
None
5.5.2.3 Get Dataset Information
You can retrieve some information on the registered dataset.
This service returns an error when the end user cannot access the dataset.
Request
URI: /api/analytics/datasets/<datasetID>
HTTP Method:GET
None
None

Response
{
"ID",
"name",
"location" : {
"schema",
"table"
},
"numberOfRows",
"numberOfColumns",
"variables" : [
{
"position",
"name",
"storage",
"value",
"key"
},
{...},
...
]
}

● schema
● table
● position
● name
● storage
● value
● key
Related Information
Get Variable Information [page 39]

5.5.2.4 Get Variable Information
You can retrieve information on a specific variable of a dataset.
This service returns description along with statistics on a specific variable of a dataset.
The statistics returned by the service depends on the following value type of the variable:
● Nominal - the list of the distinct values of this variable with their frequencies is returned
● Continuous - the minimum, maximum and average values of this variable are returned. The average value
is calculated only for numeric variables, not for dates.
The service returns an error when:
● The dataset does not exist.

● The specified variable is not valid.
Request
URI: /api/analytics/dataset/<datasetID>/variable/<variablePosition>
HTTP Method:GET
None
None
Response
The output contains the following:
● Variable information
● Statistics information, depending on the variable is nominal or continuous
Table 19: Variable Information

position Integer The position of the variable in the dataset
name String The variable name

storage String The data type of the value stored in the variable

● string: the variable contains character strings
● datetime: the variable contains dates and timestamps
value String The type of the value stored in the variable
● continuous: numeric variable of which mean or variance can be

computed
● nominal: categorical variable that is the only possible value for a
string
● ordinal: discrete, relative variable where the relative order is im
portant
Note
Ordinal variables are currently considered as either continuous or
nominal variables depending on their storage type.
key Integer A flag that indicates if the column is a component of a primary key
● 0: the variable is not a primary key

● 1: the variable is primary key
numberOfCategor Integer The number of distinct values of the variable. Only returned if the varia
ies ble is nominal.
Table 20: Statistics Information

valueStatistics Array of objects The statistics generated on the values of the variables
Nominal Variable
If the variable is nominal, there are as many category and frequency pairs as there are categories.
Table 21: Statistics Information (Nominal Variable)

category String The name of the category of the variable
frequency Number The frequency of the category in the dataset
{
"position",
"name",
"storage",
"value",
"key",
"numberOfCategories",
"valueStatistics" : [
{
"category",
"frequency"

},
{...},
...
]
}
Continuous Variable
If the variable is continuous, the statistics contain the minimum, maximum, and average values of the variable.
Table 22: Statistics Information (Continuous Variable)

minimum Number The minimum value of the variable
maximum Number The maximum value of the variable
average Number The average value of the variable
{
"position",
"name",
"storage",
"value",
"key",
"valueStatistics" : {
"minimum",
"maximum",
"average"
}
}
Example
calculated.


5.5.2.5 Modify the Variable Description
You can modify the description of the variables in the dataset.
This service allows you to:
● Correct the value types of variables, if the automatic guess did not return the correct results
● Indicate which columns are components of the primary key of the dataset
Only value types or components of the primary key can be changed. Positions, variable names, and storage
types must be the same as the ones in the physical dataset. The new description will be stored with dataset
metadata and used by default whenever the dataset is used by a service. The response contains the dataset
information with the changed value types or components of the primary key.
Note
The service does not allow partial change. If any of the changes specified in the request body cannot be
done, no change will be done.
Request
URI: /api/analytics/dataset/<datasetID>/variables/update
HTTP Method: POST
Request Query Parameters: None
[
{
"name",
"value",
"key"
},
{...},
...
]
name Yes String The name of the variable

value No String The new value of the variable, which can be one of
the following:
● continuous: numeric variable of which

mean or variance can be computed
● nominal: categorical variable that is the only
possible value for a string
● ordinal: discrete, relative variable where
the relative order is important
Note
Ordinal variables are currently considered as ei
ther continuous or nominal variables depending
on their storage type.
key No Integer The new value of the key of the variable: 1 to indi
cate that the column is part of the primary key of
the dataset, else 0.
Response
{
"ID",
"name",
"location" : {
"schema",
"table"
}
"numberOfRows",
"numberOfColumns",
"variables" : [
{
"position",
"name",
"storage",
"value",
"key"
},
{...},
...
]
}


● schema
● table
● position
● name
● storage
● value
● key
Table 24: Variables

position No Integer The position of the variable in the dataset. Null
name Yes String The variable name N/A
storage No String The data type of the value stored in the variable: N/A

● string: the variable contains character
strings
● datetime: the variable contains dates and
timestamps
value Yes String The type of the value stored in the variable: Null
● continuous
● nominal
● ordinal
key No Integer A flag that indicates if the column is a component 0

of a primary key
Example
calculated.


5.5.3 Forecasts APIs
The Forecasts service analyzes a dataset containing the successive values of a target indicator over time to
predict the next values.
This service:
● Generates forecasts based on patterns detected on the time series

● Provides information on the detected pattern: trends, cycles, fluctuations
● Provides indicators on the reliability of the results
● Enables you to modify the modeling process to improve the results (variables, forecast modeling method)
The predictive model combines the trend, cycles, and fluctuations found in the time series to generate
forecasts. The prediction also depends on information provided through extrapredictive variables if any. The
granularity of the prediction is the same as the granularity used in the dataset. For example, if the dataset
contains daily observations of a time series, the service computes the values of the series in the next days. See
the Time Series Scenarios on the SAP Help Portal for a description of the time-series components.
Note
● By default, all the variables in the dataset are taken into account to calculate the forecasts. If the dataset
contains other variables than the target column and the date column, then make sure they all have
values in the forecast period or remove them from the analysis using the skippedVariables setting.
Else, the following EXX114 error message might appear:
An internal error has occurred: The training data set does not contain
enough values for the
extra-predictable variables to cover the number of requested forecasts.
● The service may return forecasts without error bars beyond the maximum confident horizon.
APIs

Getting the fore POST /api/analytics/ input [page 46] output [page 49]
casts forecast/sync

forecast
tus forecast/<jobID>/
status
Getting the fore GET /api/analytics/ None output [page 49]

casts forecast/<jobID>

forecast/<jobID>
None
The list of input parameters for the synchronous mode and the asynchronous job creation API of the Forecasts
service.
{
"datasetID",
"targetColumn",
"dateColumn",
"numberOfForecasts",
"referenceDate",
"numberOfPastValuesInOutput",
"skippedVariables",
"weightVariable",
"smoothingCycleLength",
"forecastMethod",
"maxLag"
}

in the schema.

targetColu Yes String The name of the column containing the values of N/A
mn the time series.
dateColumn Yes String The name of the column containing the timestamps N/A
of the time series.
numberOfFo Yes Integer The number of forecasts to generate from the cur N/A
recasts rent time series.
referenceD No DateTime The last date of the data used to train the model. The date of the
ate The service generates the forecasts from the date last known
after referenceDate. In this case, the service value of the
uses only the data prior to this date. time series
Remember
The date must follow one of the two ISO 8601
formats below:
● Simple date format YYYY-MM-DD

● With timezone designator Z for the zero
UTC offset, for example:
2017-04-12T13:31:15Z.
Other formats are not supported.
numberOfPa No Integer The number of past values to return. Forecasts and 0

stValuesIn real values are provided with each past data point.
Output
The service returns the latest data points of the
time series. If a reference date is specified, then it
would be the latest data points up to the reference
date.
Caution
If numberOfPastValuesInOutput is -1,
then all past values are returned. This can be
voluminous.

tion ● variable
with the data
set is used.
● value
● key
● missing
Note
omitted.
weightVari No String The variable to be used as weight during modeling. Null. No varia
able ble is used as
weight.
smoothingC No Integer The cycle length to be used when smoothing the Null
ycleLength time series.
If null, then the cycle length is guessed from the

data. In case smoothing techniques are not used
(forecastMethod different from smoothing),
this parameter is ignored.
forecastMe No String The method used by the underlying model to gen default
thod erate the forecasts.
By default, the configuration provided by the Auto

mated Analytics is used.
The supported modeling configurations and values

are the following:
● default: the default configuration used in

Automated Analytics
● smoothing: the technique which generates
forecasts by smoothing a time-series model.
The double or triple exponential smoothing is
chosen depending on the use case.
● linear regression: the technique which
generates forecasts from a linear regression

maxLag No Integer The maximum lag to consider to compute fore The default
casts. value in Predic
tive Analytics
maxLag controls the way that time series analyzes
the random fluctuations in the signal. It defines the
maximum dependency of the signal on its own past
values.
Whenever fluctuations are detected, the last N val

ues of the time series may be used to compute
forecasts. maxLag is the maximum value that can
be allowed to N. It represents how far in time the
model is allowed to look at to compute each fore
cast.
Remember
This parameter only applies with the default
forecast method and is ignored if another fore
cast method is used.
Related Information
The list of output parameters for the synchronous and asynchronous APIs of the Forecasts service.
{
"parameters" : {
...
},
"forecasts" : [
{
"date",
"realValue",
"forecastValue",
"errorBarLowerBound",
"errorBarHigherBound"
},
{...},
...
],
"modelInformation" : {
"trend,
"cycles",
"fluctuations"
},

"qualityRating,
"mape",
"mapePerHorizon",
"maximumConfidentHorizon"
}
}

46]
forecasts [page Array of objects The forecasts.

50]
Forecasts on future dates show realValue if known,
forecastValue, errorBarLowerBound and
errorBarHigherBound both when possible. Forecasts on past dates
show realValue and forecastValue. The number of past values
returned is enabled by the numberOfPastValuesInOutput param
eter in the request.
modelInformatio Object Technical information related to the time series.

n [page 50]
The predictive model combines the trend, cycles, and fluctuations found
in the time series to generate forecasts.
modelPerformanc Object Indicators on the quality of the results.

e [page 50]
Table 30: Forecasts

date DateTime The date for which the forecast is generated.
realValue Number The actual value of the target indicator.
forecastValue Number The estimated value of the target indicator.
errorBarLowerBo Number The lower bound of error bar for current forecast.
und
errorBarHigherB Number The higher bound of error bar for current forecast.
ound
Table 31: Model Information

trend String The general orientation of the signal.
cycles String The periodic elements that can be found at least twice in the data.
fluctuations String Residuals after extraction of trend and cycles modeled through auto-re
gression.
Table 32: Model Performance


mape Number The horizon-wide Mean Absolute Percentage Error (MAPE) indicator.
Caution
If maximumConfidentHorizon is lower than
numberOfForecasts, the MAPE indicator might not be calculated
based on the performances on the whole requested horizon.
mapePerHorizon Array of numbers Array of MAPE indicators for each horizon until the requested horizon
(the value of numberOfForecasts).
This shows the evolution of the performance of the predictive model de
pending of the horizon of the forecasts. The first element of this array is
the performance at horizon 1 (the next value), the second element is the
performance at horizon 2 (the second next) and so on.
If the requested horizon is too high, performances may not be measura

ble from a certain horizon. In that case, only the available ones are pro
vided.
maximumConfiden Integer The maximum horizon for which the performance indicators are reliable.
tHorizon
For an horizon higher than maximumConfidentHorizon, the service
may provide forecasts without error bars.
Quality Rating
The following table shows the correspondence between the MAPE indicator and the quality rating.
Quality Rating MAPE
0 > 0.8
1 > 0.7
2 > 0.5
3 > 0.4
4 > 0.2
5 <= 0.2
Related Information

5.5.4 Key Influencers APIs
The Key Influencers service analyzes a dataset to identify the variables with an influence on a specified target.
This service:
● Identifies the variables with an influence on a specified target ordered by decreasing contribution
● Returns detailed information on the grouped categories for each contributive variable
● Returns the variables excluded from the analysis
● Returns the variables that are correlated with each other
Remember
The target of the dataset must be either binary or continuous. Multinomial targets are not supported.
APIs

Getting the key influ POST /api/analytics/ input [page 53] output [page 54]
encers keyinfluencer/sync

Creating the job POST /api/analytics/ input [page 53] output [page 86]
keyinfluencer
tus keyinfluencer/<jobID>/
status
Getting the key influ GET /api/analytics/ None output [page 54]
encers keyinfluencer/<jobID>

keyinfluencer/<jobID>

None
The list of input parameters for the synchronous mode API and the asynchronous job creation API of the Key
Influencers service.
{
"datasetID",
"targetColumn",
"numberOfInfluencers",
"targetKey",
"skippedVariables",
"weightVariable",
"autoSelection"
}

in the schema.

targetColu Yes String The name of the column containing the target to N/A
mn use for the analysis.
numberOfIn No Integer A positive integer that represents the number of Null. All contri
fluencers key influencers to return. butive variables
are returned.

tion ● variable
with the data
set is used.
● value
● key
● missing
Note
omitted.

targetKey No String or num The value of the target of interest. The least fre
ber quent category
able ble is used as
weight.
autoSelect No Boolean true to enable the autoselection of variables. false

ion
Related Information
The list of output parameters of the synchronous and asynchronous APIs of the Key Influencers service.
{
"parameters" : {
...
},
"influencers" : [
{
"variable",
"contribution",
"groups" : [
{
"groupName",
"groupDefinition" : {
"categories",
"higherBound",
"higherBoundIncluded",
"lowerBound",
"lowerBoundIncluded",
"kxmissingIncluded"
},
"significance",
"normalProfit",
"frequency",
"targetMean"
},
{...},
...
]
},
...
],
"qualityRating",

"predictivePower",
},
"excludedVariables" : [
{
"variable",
"reason"
},
{...},
...
],
"correlatedVariables" : [
{
"firstVariable",
"secondVariable",
"coefficient"
},
{...},
...
]
}

53]
influencers [page Array of objects The list of the top N most contributive variables and detailed information
55] on how they influence the target.
The list of influencers presents the variables, their contribution, and

grouped categories. Each variable can have one or more grouped catego
ries. A grouped category is a series of values of the variable that have a
similar behavior regarding the specified target.

e [page 56]
excludedVariabl Array of objects The list of variables that were excluded automatically from the model.
es [page 56]
correlatedVaria Array of objects The list of pairs of correlated variables found in the dataset.
bles [page 57]
Table 38: Influencers

variable String The variable name
contribution Number The contribution to the influence
groups Array of objects The grouped categories. See table below.
Table 39: Group

groupName String The name of the grouped category
groupDefinition Object The definition of the grouped category. See table below.
significance Number The impact of the grouped category

normalProfit Number The normal profit of the grouped category
frequency Number The frequency of the grouped category. This is the percentage of the da
taset that belongs to the grouped category.
targetMean Number The target average in the grouped category. If the target is a binary value,
it corresponds to the target rate inside the grouped category.
Table 40: Group Definition

categories Array of strings The list of values in the grouped category of a nominal variable. Null if the
variable is continuous.
higherBound Number The higher bound in current category range for continuous variables
higherBoundIncl Integer 1 if higher bound is included, else 0, for continuous variables

uded
lowerBound Number The lower bound in current category range for continuous variables
lowerBoundInclu Integer 1 if lower bound is included, else 0, for continuous variables

ded
kxmissingInclud Integer 1 if kxmissing is included, else 0, for continuous variables

ed
Note
The following group definition values are null if the variable is nominal:
● higherBound
● higherBoundIncluded
● lowerBound
● lowerBoundIncluded
● kxmissingIncluded

qualityRating Integer The model quality indicator in 0-5 range
ator
predictivePower Number The predictive power of the model that has generated the results
predictionConfi Number The prediction confidence of the model that has generated the results
dence
Table 42: Excluded Variable

variable String The variable name

reason String The reason why the variable has been excluded, which can be:
● Leak Variable
● Fully Compressed
● Small KI on Estimation
● Small KI on Validation
● Large KI Difference
● Small KR
● Constant
● Small variance
Note
The reason values are the ones used in SAP Predictive Analytics. The Leak Variable reason corresponds
to Suspicious Variable. For more information about the variable exclusion causes, see the Automated
Analytics User Guides and Scenarios on the SAP Help Portal.
Table 43: Correlated Variables

firstVariable String The name of the first correlated variable
secondVariable String The name of the second correlated variable
coefficient Number The coefficient of correlation of these two variables
The coefficient takes value from -1 to 1, where:
● The sign indicates whether the correlation is positive or negative.

Positive means if the first variable increases (resp. decreases), so
does the second. Negative means if the first variable increases
(resp. decreases), the second decreases (resp. increases).
● The absolute value indicates the strength of the correlation. The
higher the value is, the stronger the correlation. A value of 1 (respec
tively -1) indicate absolute positive (respectively negative) correla
tion and a value of 0 indicates no correlation.
Two variables are considered as correlated if the absolute value of their

coefficient of correlation is higher than 0.5.
Related Information

5.5.5 Outliers APIs
The Outliers service identifies the odd profiles of a dataset whose target indicator is significantly different from
what is expected.
This service:
● Identifies outliers contained in a dataset with regard to a target indicator

● Ranks the outliers to get the oddest on top
● Provides the reasons why an identified outlier is odd
An outlier can either result from a data quality issue to correct or represent a suspicious case to investigate.
Remember
APIs

Getting the outliers POST /api/analytics/ input [page 59] output [page 60]
outliers/sync

outliers
tus outliers/<jobID>/
status
Getting the outliers GET /api/analytics/ None output [page 60]

outliers/<jobID>

outliers/<jobID>

None
Outliers service.
{
"datasetID",
"targetColumn",
"numberOfOutliers",
"numberOfReasons",
"targetKey",
"skippedVariables",
"weightVariable",
"autoSelection
}

in the schema.

targetColu Yes String The name of the column containing the target. N/A
mn
numberOfOu No Integer The number of outliers to return. The value 0 re 100
tliers turns all the outliers.
numberOfRe No Integer The number of reasons to output for each outlier 3

asons

scription Cau scription stored
ing parameters that describe the variable:
tion with the data
● variable set is used.
Deprecated
● storage
● value
● key
● missing
Note
omitted.
targetKey No String or num The value of the target of interest. The least fre
ber quent category
able ble is used as
weight.
autoSelect No Boolean true to enable the autoselection of variables. false

ion
Related Information
The list of output parameters for the synchronous and asynchronous APIs of the Outliers service.
{
"parameters" : {
...
},
"numberOfOutliers",
"outliers" : [
{
"dataPoint",
"predictedValue",
"errorBar",
"realValue",
"reasons" : [
{

"variable",
"value"
}
]
},
{...},
...
],
"qualityRating",
"predictivePower",
}
}
parameters [page 59] Object The content of the request body.
numberOfOutliers Integer The total number of outliers found in the dataset.
outliers [page 61] Array of objects The list of outliers, including their reasons.
An observation is considered as an outlier if the difference

between its predicted value and its real value exceeds the
value of the error bar. A reason is a {variable, value} pair that
has caused the target value to be overestimated or underes
timated.
modelPerformance An object Indicators on the quality of the results.

[page 61]
Table 49: Outliers

dataPoint Object The content of the record flagged as an outlier, that is, the values of all
the dataset columns for this record.
predictedValue Number The expected value of the target indicator computed from each attribute
value of a record.
errorBar Number The error bar associated with the expected value.
realValue String The real value of the target indicator.
reasons Array of objects The reasons.
Table 50: Reasons

variable String The variable associated with the reason.
value String The value associated with the reason.


ator
predictivePower Number The predictive power of the model that has generated the results.
predictionConfi Number The prediction confidence of the model that has generated the results.
dence
Related Information
5.5.6 Recommendation APIs
The Recommendation APIs provide a set of services that allows you to create a recommendation model and
generate recommendations from it.
The services compute the model and its recommendations based on a transaction dataset. The dataset
contains information about user transactions, which consist of customer/purchased item pairs.
Related Information
Manage a Recommendation Model [page 62]

Get Recommendations for a Specific User [page 68]
Get Recommendations for a Group of Users [page 71]
5.5.6.1 Manage a Recommendation Model
This Recommendation service creates a recommendation model from the user transaction history.
This service:
● Estimates the costs and performance of a recommendation model before you create it
● Creates a recommendation model, either in synchronous mode or asynchronous mode
● Returns statistics on the input transaction data, such as the number of rows, which gives an idea of the size
of the dataset
● Returns statistics on the selected recommendation rules for the created model
● Deletes the recommendation model and the corresponding job
The estimates include the duration of the process and the size of the resulting model.

This service can create recommendation rules based on the following:
● A dataset that contains the user transaction history

● A period of time that restricts the dataset content
● Settings used to configure the modeling process
The rules created are stored in the service schema.
Remember
In synchronous mode, the call also generates a job to make the recommendation model accessible. The call
outputs the job identifier, which is also the model identifier.
Recommender APIs

Creating a recom POST /api/analytics/ input [page 64] output [page 66]
mendation model recommendations/
recommender/sync
Estimating the costs POST /api/analytics/ input [page 64] output [page 67]
of a recommenda recommendations/
tion model before recommender/guess/
creation sync

recommendations/
recommender
tus recommendations/
recommender/<jobID>/
status
Getting information GET /api/analytics/ None output [page 66]

on the recommen recommendations/
dation model recommender/<jobID>
Deleting the job and DELETE /api/analytics/ None None

the recommenda recommendations/
tion model recommender/<jobID>

<jobID> Yes Integer The job identifier that you get by creating a job first.
Remember
This is also the identifier of the recommendation model.
None
5.5.6.1.1 Request Body Parameters
The list of input parameters for the synchronous mode API and the asynchronous job creation API that create a
recommendation model.
{
"transactionData" : {
"datasetID",
"transaction" : {
"userColumn",
"itemColumn",
"dateColumn"
},
"period" :{
"startDate",
"endDate"
}
},
"modelingSettings" : {
"minimumSupport",
"minimumConfidence",
"minimumPredictivePower",
"bestSellersThreshold"
}
}
transactionData Yes Object The details on the transaction data that is used
[page 65] to create the recommendation model.
modelingSetting No Object The settings of the modeling process to create

s [page 65] the recommendation model.

Table 54: Transaction Data
in the schema.
transactio Yes Object The list of the dataset columns that define a trans N/A
n action.
period No Object The time period of the dataset on which the crea N/A
tion of the model is based.
By default, no time period is defined. The recom

mendation model is created using all available data.
Table 55: Transaction

userColumn Yes String The name of the column containing the user IDs re N/A
lated to a transaction.
itemColumn Yes String The name of the column containing the item IDs re N/A
dateColumn Yes String The name of the column containing the date or N/A
timestamp of the transaction.
Table 56: Period

startDate No DateTime The start date of the time period. null
This value is included in the time period. By default,

no start date is defined.
endDate No DateTime The end date of the time period. null

no end date is defined.
Table 57: Modeling Settings

minimumSup No Integer The minimum number of occurrences of an associ 2

port ation to be considered as a recommendation rule.
minimumCon No Number The minimum confidence of a recommendation 0.5

fidence rule.
Recommendation rules whose confidence is strictly

below this value are discarded. If null, then the serv
ice does not use any threshold on confidence to se
lect the recommendation rules.

minimumPre No Number The minimum predictive power of a recommenda null

dictivePow tion rule.
er
Recommendation rules whose predictive power is
strictly below this value are discarded. If null, then
the service does not use any threshold on predic
tive power to select the recommendation rules.
bestSeller No Integer The threshold above which an item is considered as 50000

sThreshold a bestseller.
If the number of occurrences of an item in the data

set is higher than this value, then this item is con
sidered as a bestseller.
All bestsellers are excluded from the model, which

means:
● A recommendation cannot be based on this

item.
● This item cannot be recommended directly by
the recommendation model.
● Bestsellers can only complete a recommenda
tion list in order to reach the maximum num
ber of recommendations per user.
Related Information
5.5.6.1.2 Response Body Parameters
The list of output parameters for the synchronous and asynchronous APIs that create a recommendation
model.
{
"parameters" : {...},
"recommenderID",
"transactionDataStatistics" : {
"numberOfRows",
"numberOfUsers",
"numberOfItems",
"numberOfUserItemPairs",
"density"
},
"modelMetrics" : {
"numberOfRules",
"numberOfItems",
"percentageOfItems"
}
}


64]
recommenderID Number The identifier of the recommender job to access the resulting recom
mendation model.
transactionData Object A summary of the statistics of the dataset used to generate the recom
Statistics [page mendations.
67]
modelMetrics Object Statistics about the generated model and the possible recommended
[page 67] items.
Table 58: Transaction Data Statistics

numberOfRows Integer The number of rows in the transaction dataset.
numberOfUsers Integer The number of distinct users in the transaction dataset.
numberOfItems Integer The number of distinct items in the transaction dataset.
numberOfUserIte Integer The number of distinct user/item pairs in the transaction dataset.
mPairs
density Number The ratio between the number of existing user/item pairs and the total
number of possible user/item pairs.
Table 59: Model Metrics

numberOfRules Integer The number of recommendation rules in the recommendation model.
numberOfItems Integer The number of distinct items that can be recommended by this model.
percentageOfIte Number The percentage of items that can be recommended by this model com
ms pared to the total number of distinct items in the dataset
(transactionDataStatistics.numberOfItems).
Related Information
The list of output parameters of the "guess" API of the Recommendation service.
{
"numberOfRows",
"numberOfUsers",

"numberOfItems",
"density"
},
"estimates" : {
"rulesCountRange",
"modelingProcessDuration"
}
}
transactionDataStat Object A summary of the statistics of the dataset used to generate

istics [page 68] the recommendations.
estimates [page 68] Object The estimation of the costs and size of the recommendation
model that would result from the call [POST] /api/
analytics/recommender with the same request.

numberOfRows Integer The number of rows in the transaction dataset
numberOfUsers Integer The number of distinct users in the transaction dataset
numberOfItems Integer The number of distinct items in the transaction dataset
numberOfUserIte Integer The number of distinct user/item pairs in the transaction dataset
mPairs
number of possible user/item pairs
Table 61: Estimates

rulesCountRange Array of integers The range of the number of rules in the recommendation model
modelingProcess Integer An estimate in seconds of the time required to create the recommenda
Duration tion model
Related Information
5.5.6.2 Get Recommendations for a Specific User
You can get a list of recommendations from a recommendation model for a specific user.
This service returns:
● A list of recommendation items either from a user ID or from a set of items

● A score and rank associated with each recommendation item
Scores and ranks are computed with the metrics selected and passed in the request.
By using the fillList parameter, this service guarantees the users always get recommendations,
independently of their purchase history. Bestsellers items can be added to the recommendation list if the
maximum number of items that can be recommended for a user is not reached. They are called fillers in that
case. Bestsellers are items with the highest frequencies in the dataset. They do not have any score associated.
This service also identifies which items are part of the user purchase history and allows you not to recommend
them. By default, purchased items are not recommended.
Request
From a User ID
URI: /api/analytics/recommendations?
recommenderID=<integer>&userID=<string>&maxItems=<integer>&rankingMetric=<enum>&fil
lList=<boolean>&skipAlreadyOwned=<boolean>
From a List of Items
URI: /api/analytics/recommendations?
recommenderID=<integer>&itemList=<string>,<string>,...&maxItems=<integer>&rankingMe
tric=<enum>&fillList=<boolean>&skipAlreadyOwned=<boolean>
HTTP Method: GET
recommend Yes Integer The identifier of a recommendation model created. N/A

erID
In asynchronous mode, the identifier is the job ID.
userID No String The ID of the user for whom the service generates recom N/A
mendations.
Recommendations are based on the current state of the

user purchase history in the transaction dataset.
itemList No Array of The list of items used as basis to generate recommenda N/A
strings tions
Note
If userID and itemList are both specified in the re
quest, then the service generates recommendations us
ing the values of itemList and filters them according
to the user purchase history.

maxItems Yes Integer The maximum number of recommendations to be returned N/A

by the service.
There may be less recommendations than requested, unless

the fillList option is set to true.
rankingMe No String The metric used to rank the items in the recommendation CONFIDENC
tric list. E
Possible values are:
● SUPPORT
● LIFT
● CONFIDENCE
● KI
● COSINE
● ADDED_VALUE
fillList No Boolean A flag that indicates whether the recommendation list must false
be filled until the maximum number of items (maxItems) is
reached.
If true, the recommendation list is completed with bestsell

ers items.
skipAlrea No Boolean A flag that indicates whether purchased items are removed true
dyOwned from the recommendation list.
Purchased items are those of the user purchase history if

userID is specified, or those of the item list if itemList
is specified.
If true, these items cannot be recommended.
None
Response
[
{
"itemID",
"itemScore",
"itemRank",
"isFiller"
},
{...},
...
]

itemID String The identifier of the recommended item
itemScore Number The score associated with the recommendation, using the specified
ranking metrics.
If the recommended item is used as filler, then no score is associated.
itemRank Integer The rank of the recommended item in the recommendation list
isFiller Boolean A flag indicating whether a recommended item is used as filler.
isFiller is not in the response if the fillList is set to false.
5.5.6.3 Get Recommendations for a Group of Users
This Recommendation service generates recommendations from a recommendation model for all users or a
subset of users of a dataset.
This service:
● Generates a list of recommendations either in synchronous mode or asynchronous mode and stores it in
an SAP HANA database table
● Returns statistics on the input transaction data
● Returns statistics on the generated recommendations
● Deletes the batch job
This service can generate recommendations based on the following:
● A recommendation model identified by its job ID

● A dataset that contains the user transaction history
● A period of time that restricts the dataset content
● A list of users for whom to generate recommendations
● Settings used to configure the recommendation generation
By using the fillList parameter, this service guarantees the users always get recommendations,
independently of their purchase history. Bestsellers items can be added to the recommendation list if the
maximum number of items that can be recommended for a user is not reached. They are called fillers in that
case. Bestsellers are items with the highest frequencies in the dataset. They do not have any score associated.
This service also identifies which items are part of the user transaction history and allows you not to
recommend them. By default, items already purchased are not recommended.
Remember
The predictive service DB user must be granted CREATE ANY and INSERT permissions to the destination
schema in order to write resulting recommendations in the destination table.

Batch Recommendation APIs

Generating recom POST /api/analytics/ input [page 72] output [page 76]
mendations recommendations/
batch/sync

recommendations/batch
tus recommendations/
batch/<jobID>/status
Getting statistics on GET /api/analytics/ None output [page 76]

recommendations recommendations/
batch/<jobID>

recommendations/
batch/<jobID>
<jobID> Yes Integer The job identifier that you get by creating a job first.
5.5.6.3.1 Request Body Parameters
The list of input parameters for the synchronous mode API and the asynchronous job creation API that return
recommendations for a group of users.
{
"recommenderID",
"maxItemsPerUser",
"destination" : {
"schema",
"table",

"overwrite"
},
"transactionData" : {
"datasetID",
"transaction" : {
"userColumn",
"itemColumn",
"dateColumn"
},
"period" : {
"startDate",
"endDate"
}
},
"users",
"recommendationSettings" : {
"rankingMetric",
"threshold",
"fillList",
"skipAlreadyOwned"
}
}
recommende Yes Integer The identifier of a recommender job. The recom N/A
rID mendation model resulting from this job will be
used to generate recommendations.
Note
The job must have a SUCCESSFUL status for
the service to generate recommendations.
maxItemsPe Yes Integer The maximum number of recommendations the N/A

rUser service generates per user.
destinatio Yes Object The SAP HANA database table where recommen N/A
n [page 74] dations are stored.
Note
The SAP HANA user subaccount used by the
service must have CREATE ANY and INSERT
rights granted on the destination schema or ta
ble to write the resulting data.
transactio No Object The details on the transaction data that is used to null
nData [page generate recommendations.
74]
If not specified, the dataset used to create the rec
ommendation model is used with the same defini
tion of a transaction. All other settings related to
the transaction data have default values.

users No Array of strings The list of user IDs for which the service generates By default, rec
recommendations. ommendations
are generated
for all users of
the transaction
dataset.
recommenda No Object Settings which impact the content of the recom N/A
tionSettin mendation list.
gs [page 75]
Table 64: Destination

schema Yes String The destination schema. N/A
table Yes String The destination table name. N/A
The table has the following columns with the follow

ing data types:
● CONSEQUENT (item column data type)

● SCORE (Double)
● IS_FILLER (Integer)
● FILLER_SCORE (Double)
● USER (user column data type)
● RANK (BigInt)
overwrite No Boolean A flag indicating whether the destination table is false

overwritten if it exists.
Table 65: Transaction Data

in the schema.
transactio Yes Object The list of the dataset columns that define a trans N/A
n action.
period No Object The time period of the dataset on which the crea By default, no
tion of the model is based. time period is
defined. The
recommenda
tion model is
created using
all available
data.
Table 66: Transaction

userColumn Yes String The name of the column containing the user IDs re N/A

itemColumn Yes String The name of the column containing the item IDs re N/A
dateColumn Yes String The name of the column containing the date or N/A
timestamp of the transaction.
Table 67: Period

startDate No DateTime The start date of the time period. null

no start date is defined.
endDate No DateTime The end date of the time period. null

no end date is defined.
Table 68: Recommendation Settings (ranking and constraint settings)

rankingMet No String The metrics used as score to sort the recommen CONFIDENCE
ric dations.
Possible values are:
● SUPPORT
● LIFT
● CONFIDENCE
● KI
● COSINE
● ADDED_VALUE
threshold No Number The threshold of the ranking metrics above which null
an item is kept in the recommendation list.
By default, no threshold is defined.
fillList No Boolean A flag indicating whether a recommendation list is false

completed with bestsellers in order to reach the
maximum number of recommendations per user.
If true, the service adds bestsellers to the list.
skipAlread No Boolean A flag indicating whether an item which is already true

yOwned part of a user transaction history is removed from
the recommendation list.
By default, the item cannot be recommended.
Related Information

The list of output parameters for the synchronous and asynchronous APIs that return recommendations for a
group of users.
{
"parameters" : {...},
"numberOfRows",
"numberOfUsers",
"numberOfItems",
"density"
},
"recommendationsStatistics" : {
"numberOfRecommendations",
"numberOfUsers",
"percentageOfUsers",
"numberOfItems",
"percentageOfItems"
}
}

72]
transactionData Object A summary of the statistics of the dataset used to generate the recom
Statistics [page mendations.
76]
recommendations Object Statistics on the generated recommendations.

Statistics [page
76]

numberOfRows Integer The number of rows in the transaction dataset.
numberOfUsers Integer The number of distinct users in the transaction dataset.
numberOfItems Integer The number of distinct items in the transaction dataset.
numberOfUserIte Integer The number of distinct user/item pairs in the transaction dataset.
mPairs
number of possible user/item pairs.
Table 70: Recommendation Statistics

numberOfRecomme Integer The number of recommendations generated.

ndations
numberOfUsers Integer The number of distinct users which have at least one recommendation.

percentageOfUse Number The percentage of users which have at least one recommendation com
rs pared to the total number of distinct users in the dataset
(transactionDataStatistics.numberOfUsers).
numberOfItems Integer The number of distinct recommended items
percentageOfIte Number The percentage of recommended items compared to the total number of
ms distinct items in the dataset
(transactionDataStatistics.numberOfItems).
Related Information
5.5.7 Scoring Equation APIs
The Scoring Equation service builds a predictive model from a dataset and exports its scoring equation to
either an SAP HANA SQL query or a score card in CSV format.
This service:
● Returns the scoring equation of a predictive model

The scoring equation generates predicted values for each data point of the specified dataset. In regression
cases, the predicted value corresponds to an estimation of the value of the target indicator. In classification
cases, the predicted value corresponds to a score. The more likely a data point is a target, the higher the score
is. This score does not have any semantics and can only be used to sort out data points from more likely to less
likely to be a target. However, it can be converted into a probability by setting the predictedOutputType
parameter to probability.
Remember
APIs

Getting the scoring POST /api/analytics/ input [page 78] output [page 80]
equation scoringequation/sync

Step HTTP Method URI Request Body Response Body
scoringequation
tus scoringequation/
<jobID>/status
Getting the scoring GET /api/analytics/ None output [page 80]

equation scoringequation/
<jobID>

scoringequation/
<jobID>
None
Scoring Equation service.
{
"datasetID",
"targetColumn",
"predictionOutputType",
"equationFormat",
"keyColumn",
"datasetName",
"targetKey",
"skippedVariables",
"weightVariable",
"autoSelection"
}

datasetID Yes Integer The identifier of a dataset that has been regis N/A
tered in the schema

targetColu Yes String The name of the column containing the target to N/A
mn use for the analysis
prediction No String The type of prediction generated by the scoring predicted

OutputType equation. Possible values are: value
● predicted value
In the case of a regression, the predicted
value corresponds to an estimate of the
value of the target indicator.
In the case of a classification, this is the like
lihood of the target event in the form of a
score. Scores do not have semantics and
can only be used to sort out the data point
from more likely to less likely.
● probability
In the case of a classification, this is the like
lihood of the target event in the form of a
probability. In the case of a regression, the
output is the same as for predicted
value.
equationFo Yes String Format of the scoring equation of the resulting N/A
rmat model:
● HANA: the scoring equation is exported as

an SAP HANA SQL query.
● CSV: the scoring equation is exported as a
score card in a CSV file.
keyColumn No String The name of the column considered as key. Ap $Key. The $Key
plicable only if equationFormat is HANA. variable must
be set when ex
ecuting the
SQL query.
datasetNam No String The name of the table which the scoring equation $Dataset. The
e is applied to. Applicable only if $Dataset varia
equationFormat is HANA. ble must be set
when executing
the SQL query.

variableDe Array of objects The tuples are name and value pairs for the fol Null. The de
scription Cau lowing parameters that describe the variable: scription
tion ● variable
stored with the
dataset is used.
● value
● key
● missing
Note
Only variable, storage, and value
must be in the input. The other parameters
can be omitted.
targetKey No String or number The value of the target of interest The least fre
quent category
iables the analysis excluded.
weightVari No String The variable to be used as weight during model Null. No varia
able ing ble is used as
weight.
autoSelect No Boolean true to enable the autoselection of variables true

ion
Related Information
The list of output parameters of the synchronous and asynchronous APIs of the Scoring Equation service.
{
"parameters": {
...
},
"scoringEquation”,
"qualityRating",
"predictivePower",
}
}


78]
scoringEquation String The scoring equation of the predictive model.

e [page 81]

qualityRating Integer The model quality indicator in 0-5

range.
confidenceIndicator Integer The model robustness indicator. 1 if the

results are reliable, else 0.
predictivePower Number The predictive power of the model that

has generated the results.
predictionConfidence Number The prediction confidence of the model

that has generated the results.
Related Information
5.5.8 What If APIs
The What If service simulates a planned action and returns the significant changes that result from it.
This service:
● Provides the list of deviant variables

● Provides the list of deviant categories for each deviant variable
● Provides statistics of the variable on both original and simulation datasets
The simulation consists of changing the weight assigned to a group of values of the variable. The service
returns the deviations observed on the series of variables affected by this change and lists the affected
categories for each of them. It also compares the frequency of each category before and after the change is
applied.

APIs

Running the simula POST /api/analytics/ input [page 82] output [page 84]
tion whatif/sync

Creating a job POST /api/analytics/whatif input [page 82] output [page 86]
tus whatif/<jobID>/status
Getting the results GET /api/analytics/ None output [page 84]

of the job whatif/<jobID>

whatif/<jobID>
None
The list of input parameters for the synchronous mode API and the asynchronous job creation API of the What
If service.
{
"datasetID",
"simulation":{
"variable",
"weights": [
{
"categories",
"range":{
"lowerBound",
"lowerBoundIncluded",
"higherBound",

"higherBoundIncluded",
"kxmissingIncluded"
}
"weight"
},
{...},
...
]
}
"skippedVariables",
"weightVariable"
}
in the schema.
simulation Yes Object The simulation parameters. N/A

[page 83]
tion ● variable
with the data
set is used.
● value
● key
● missing
Note
omitted.
weightVari No String The existing weight variable to be considered in the Null. No varia
able analysis. ble is used as
weight.
Table 79: Simulation Settings

variable Yes String The variable whose distribution is modified for the N/A
sake of the simulation.
weights Yes Array of objects The list of changes to apply to the variable. Each N/A
change corresponds to a new weight assigned to a
specific group of values. A group is specified either
as a set of values or a range of values.

Table 80: Weights
categories No Array of strings The set of values, which a new weight is assigned N/A
to. This list can contain strings but cannot contain
null values.
range No Object The range of values, which a new weight is assigned N/A
to.
weight Yes Number The new weight assigned to a group for the simula N/A
tion.
Remember
You must specify either categories or range. The service returns an error if both are specified.
Table 81: Range

lowerBound No Number The lower bound in current category range. N/A
lowerBound No Integer 1 if lower bound is included, else 0. N/A

Included
higherBoun No Number The higher bound in current category range. N/A

d
higherBoun No Integer 1 if higher bound is included, else 0. N/A

dIncluded
kxmissingI No Integer 1 if the group also includes missing values, else 0. N/A
ncluded
Related Information
The list of output parameters of the synchronous and asynchronous APIs of the What If service.
{
"parameters" : {
...
},
"deviations" : [
{
"variable",
"categories",
"statistics" : [
{
"category",

"originalFrequency",
"simulationFrequency",
"frequencyIncrease"
},
{...},
...
]
},
...
],
}

82]
deviations [page Array of objects The list of the deviations observed after simulation.
85]
Table 82: Deviations

variable String The deviant variable name
categories Array of strings The list of all the deviant categories for the current deviant variable
statistics Array of objects The comparison data of the current deviant variable between the original
and simulation datasets. See table below.
Table 83: Statistics

category String The category name, which can be:
● A specific value if the variable is nominal

● A range of values if the variable is continuous
originalFrequen Number The frequency of the current category in the original dataset
cy
simulationFrequ Number The frequency of the current category in the simulation dataset
ency
frequencyIncrea Number The relative increase of the frequency of the current category between
se the original and simulation datasets
Related Information

5.5.9 Job Response Body Parameters
The list of output parameters of the job creation and status check APIs.
{
"id",
"status",
"type",
"input": "{
}"
}
id Nonnull, positive integer The job identifier
status String The job status:
● NEW
● PROCESSING
● SUCCESSFUL
● FAILED
type String The service associated with the job:
● clustering
● forecasts
● key_influencer
● outliers
● recommender
● recommendations_batch
● scoring_equation
● whatif
input Object A summary of the input parameter val

ues
Related Information

Recommendation APIs [page 62]

5.6 Usage Scenarios
The following scenario illustrates a typical usage of the Clustering service.
5.6.1 Creating Clusters with Either High or Low Target Rate
With this scenario, the end user will be able to segment a population into "interesting" / "not interesting"
clusters and focus on specific clusters of interest instead of the whole population.
Step Description
Register the dataset and specify the primary key Registering the Dataset [page 87]
Create the clustering model in asynchronous mode Calling the Clustering Service [page 92]
Get the clustering job results Getting the Results [page 94]
Get access to segmentation results Accessing the Segmentation Results [page 95]
5.6.1.1 Registering the Dataset
The SAP HANA schema is DATA_SCHEMA and contains the CENSUS dataset, which has the id column as
primary key. OUTPUT_SCHEMA is the schema that will contain the output table of the clustering process.
The end user:
● Can use the clustering service

● Has access to the OUTPUT_SCHEMA schema
The predictive service:
● Has SELECT rights on DATA_SCHEMA

● Has CREATE_ANY right on OUTPUT_SCHEMA
Note
For a description of the CENSUS dataset, see Datasets Available for SAP API Business Hub [page 164].
Request
URI: /api/analytics/dataset/sync
HTTP Method: POST
Request body:

"hanaURL": "DATA_SCHEMA/CENSUS_ORDERED"
}
Response
The service generates the ID 118 for the CENSUS_ORDERED view.
{
"ID": 118,
"name": "CENSUS",
"numberOfColumns": 16,
"numberOfRows": 48842,
"variables": [
{
"name": "id",
"position": 0,
"storage": "integer",
"value": "continuous"
},
{
"name": "age",
"position": 1,
},
{
"name": "workclass",
"position": 2,
"storage": "string",
"value": "nominal"
},
{
"name": "fnlwgt",
"position": 3,
},
{
"name": "education",
"position": 4,
"value": "nominal"
},
{
"name": "education-num",
"position": 5,
"value": "nominal"
},
{
"name": "marital-status",
"position": 6,
"value": "nominal"
},
{
"name": "occupation",
"position": 7,
"value": "nominal"
},
{
"name": "relationship",

"position": 8,
"value": "nominal"
},
{
"name": "race",
"position": 9,
"value": "nominal"
},
{
"name": "sex",
"position": 10,
"value": "nominal"
},
{
"name": "capital-gain",
"position": 11,
"value": "nominal"
},
{
"name": "capital-loss",
"position": 12,
"value": "nominal"
},
{
"name": "hours-per-week",
"position": 13,
},
{
"name": "native-country",
"position": 14,
"value": "nominal"
},
{
"name": "class",
"position": 15,
"value": "nominal"
}
]
}
Specifying the Primary Key of the Dataset
A dataset does not require a primary key to use the clustering service. However, if it does not have one, the
performances will be hindered, as the whole dataset is copied to the segmentation results. To specify a primary
key, modify the description of the id column of the dataset and indicate it is the only component of the primary
key. In this scenario, correct the description of some variables at the same time.

Request
URI: /api/analytics/dataset/118/variables/update
HTTP Method: POST
Request body:
[
{
"name" : "id",
"value" : "nominal",
"key" : 1
},
{
"name" : "education-num",
"value" : "ordinal"
},
{
"name" : "capital-gain",
"value" : "continuous"
},
{
"name" : "capital-loss",
"value" : "continuous"
}
]
Response
This is the updated version of the dataset.
{
"ID": 118,
"name": "CENSUS",
"numberOfColumns": 16,
"numberOfRows": 48842,
"variables": [
{
"name": "id",
"position": 0,
"value": "nominal",
"key" : 1
},
{
"name": "age",
"position": 1,
},
{
"name": "workclass",
"position": 2,
"value": "nominal"
},
{
"name": "fnlwgt",
"position": 3,

},
{
"name": "education",
"position": 4,
"value": "nominal"
},
{
"name": "education-num",
"position": 5,
},
{
"name": "marital-status",
"position": 6,
"value": "nominal"
},
{
"name": "occupation",
"position": 7,
"value": "nominal"
},
{
"name": "relationship",
"position": 8,
"value": "nominal"
},
{
"name": "race",
"position": 9,
"value": "nominal"
},
{
"name": "sex",
"position": 10,
"value": "nominal"
},
{
"name": "capital-gain",
"position": 11,
},
{
"name": "capital-loss",
"position": 12,
},
{
"name": "hours-per-week",
"position": 13,
},
{
"name": "native-country",
"position": 14,
"value": "nominal"

},
{
"name": "class",
"position": 15,
"value": "nominal"
}
]
}
5.6.1.2 Calling the Clustering Service
Start the clustering process with the following constraints:
● Not too many clusters, as each cluster would require a specific analysis (4 or 5)
● The clustering process is driven by a target indicator (class column) to ideally get clusters with high or
low target rate. That way, you can focus on first ones and ignore the last ones.
● Export the segmentation results to a table called MY_CLUSTERING table of the OUTPUT_SCHEMA schema.
Send an asynchronous call that creates a clustering job. The job creates, trains, applies, and deletes a
clustering model.
Request
URI: /api/analytics/clustering
HTTP Method: POST
Request body:
{
"datasetID" : 118,
"numberOfClusters" : [4, 5],
"method" : "table",
"destination" : {
"schema" : "OUTPUT_SCHEMA",
"table" : "MY_CLUSTERING"
}
},
"target" : {
"column" : "class",
"value" : 1
}
}
Response
The service generates the ID 7 for the clustering job.

"ID": 7,
"status": "PROCESSING",
"type": "clustering",
"input":
"datasetID" : 118,
"method" : "table",
"destination" : {
}
},
"target" : {
"column" : "class",
"value" : 1
}
}
Checking the Job Status
Check whether the job is finished.
Request
URI: /api/analytics/clustering/7/status
HTTP Method: GET
Request body: none
Response
{
"ID": 7,
"status": "SUCCESSFUL",
"type": "clustering"
}

5.6.1.3 Getting the Results
Get the clustering job results with the following call:
Request
URI: /api/analytics/clustering/7
HTTP Method: GET
Request body: none
Response
The job results contain:
● A reminder of the parameters used for the clustering

● Some clustering metrics
● The list of clusters resulting from the clustering
● The location where the cluster assignment information is exported
● Indicators on the performance of the clustering model
{
"parameters" : {
"datasetID" : 118,
"method" : "table"
"destination" : {
}
},
"target" : {
"column" : "class",
"value" : 1
}
},
"clustering" : {
"numberOfClusters" : 4
},
"clusters" : [
{
"ID" : 1,
"name" : "Cluster_1",
"frequency" : 0.0635,
"targetMean" : 0.7708
},
{
"ID" : 2,
},

{
"ID" : 3,
},
{
"ID" : 4,
}
],
"results" : {
"view" : "MY_CLUSTERING"
}
"qualityRating" : 4,
"confidenceIndicator" : 1,
"predictivePower" : 0.6869,
"predictionConfidence" : 0.9944
}
}
The clustering model has segmented all the data points of the dataset into four clusters:
● Cluster 1 has a high target rate (77%), but it is a bit small (6% of the dataset).
● Cluster 3's target rate is a bit lower (64%), but it is twice as big (15%).
● Cluster 2's target rate is really low, which means targets from this cluster should be ignored
● Nothing special comes from Cluster 4.
The clustering model has a high predictive power (69%), which means the cluster ID assigned to a data point is
a useful information to deduce the value of the target variable. The clusters are stable (prediction confidence =
99%), which means the cluster ID is a reliable information to deduce the value of the target of a data point.
The cluster assignment information has been successfully exported to the MY_CLUSTERING table of the
OUTPUT_SCHEMA schema.
5.6.1.4 Accessing the Segmentation Results
Cluster assignment information is now available to the MY_CLUSTERING table. Since a primary key and a target
have been specified, this table only contains:
● The primary key column id

● The target column class
● The cluster ID column CLUSTER_ID
You can get the complete view of the segmentation results where each data point has an additional column
containing their assigned cluster ID. Create the MY_CLUSTERING_FULL view to merge the CENSUS table and
the MY_CLUSTERING table using the id column as merge key.
CREATE VIEW "DATA_SCHEMA"."MY_CLUSTERING_FULL" as

select c.*, mc."CLUSTER_ID"
from "DATA_SCHEMA"."CENSUS" c
inner join "OUTPUT_SCHEMA"."MY_CLUSTERING" mc on c."id"=mc."id"
order by "id"

Then select the view and see the merged tables
select * from "DATA_SCHEMA"."MY_CLUSTERING_FULL"
5.7 Error Messages Explained
Error messages may appear while you are using the predictive service.
If the request was unsuccessful, the call returns a message in the JSON format, as follows:
{
"errors":[
{
"errorCode": string,
"errorMessage": string
},
{...},
...
]
}
This section lists the messages and their descriptions.
Related Information
General Service Parameter Error Messages (EXX) [page 97]

Database Error Messages (EDB) [page 98]
Dataset Service Error Messages (EDS) [page 99]
Job Access Error Messages (EJB) [page 100]
Modeling Parameter Error Messages (EMO) [page 100]

5.7.1 General Service Parameter Error Messages (EXX)
Error Code HTTP Code Error Message Error Cause
EXX100 500 An error has occurred. This is the default error message.
EXX101 400 The mandatory <parameter> parame You do not specify one of the manda
ter is missing. Please set tory parameters.
<parameter>.
EXX102 400 The "<variable>" variable used as The dataset does not contain the speci
<parameter> was not found in the da fied variable.
taset.
EXX103 400 The "<variable>" variable is used as The specified variable does not have
<parameter> but its storage type is the required storage type.
identified as <real storage type>.
A variable used as <parameter> must
have one of the following storage
types : <storageType,
storageType2, …>.
EXX104 400 The "<variable>" variable is used as The specified variable does not have
<parameter> but its value type is iden the required value type.
tified as <real value type>. A varia
ble used as <parameter> must have
one of the following value types :
<valueType, valueType2, …>.
EXX105 400 The <parameter> parameter does not The current parameter does not sup
support the value "<value>". The sup port the specified value.
ported values are "<value1,
value2…>".
EXX106 400 The "<variable>" variable does not The dataset does not contain the speci
contain a "<value>" value. fied value.
EXX107 400 The <parameter> parameter must be The value specified for the current pa
a positive integer. rameter must be a positive integer.
EXX108 500 The service cannot access the dataset The dataset identifier used with the
<datasetID>. service is not accessible.
EXX109 400 The "<variable>" variable is used A variable is used with 2 or more roles.
with multiple roles: <role1, role
2>.
EXX110 500 An SQL error has occurred. Various issues returned by the SAP
HANA database, for example: a table
that does not exist, wrong credentials,
and so on.
EXX111 400 You must specify either Only one parameter must be defined
"<parameter1>",… or "<parameter>" among a list of parameters. Either no or
parameter. several parameters have been defined.
EXX112 403 The dataset cannot contain a variable The name of a variable of the dataset
named "<variable>". Please rename corresponds to a variable internally cre
this variable before using the service. ated by the service.

EXX113 400 <parameter> is not a valid parameter. One of the request parameter is not
Please refer to documentation for the valid.
JSON Schema of the request body of
the service.
EXX114 500 An internal error has occurred : An error occurred while training a data
<submessage>. mining model. <submessage> refers to
an error message raised by the predic
tive model engine.
EXX115 400 The <parameter> parameter requires The number of values of one of the ar
at least <n> values. ray type parameters is lower than the
minimum required number of values.
EXX116 400 The value set for the <parameter> pa The value assigned to one of the re
rameter is not valid. quest parameters is not valid.
EXX117 400 The job specified as <setting> must One of the setting refers to a job which
refer to an existing <type> job with a either is not accessible or does not
SUCCESSFUL status. have a SUCCESSFUL status.
EXX118 400 <schema>.<table> is specified both The destination table cannot be the ta
as input dataset and destination table. ble used as input dataset.
EXX119 400 The body of the request is not a valid There are syntax issues in the request.
JSON string.
EXX120 403 The service cannot write inside The service cannot write inside the
<schema>.<table>. specified destination table. Possible
causes are the following:
● The schema is not accessible.

● The service does not have permis
sion to create the destination ta
ble.
● The destination table exists and
the service won't overwrite it.
EXX121 400 The <parameter> cannot be set to The following combination of parame
<value> if <parameter2> is set to ters is not valid.
<value2>.
5.7.2 Database Error Messages (EDB)
EDB001 500 Error DB connection: <message>. An SAP HANA database-related error

has occurred.
EDB002 500 Datasource not initialized: bind The binding does not exist or has not
ing=<binding_name> been initialized properly.
EDB003 500 No datasource, binding does not exist: The binding has been initialized but
binding=<binding_name> can’t be used.

5.7.3 Dataset Service Error Messages (EDS)
EDS101 400 "<hanaURL>" is not accessible. Please The datasource URL is not accessible.
make sure that hanaURL is correct and
that access rights were granted to the
predictive services.
EDS102 404 The dataset <datasetID> was not The dataset ID does not exist or is un
found. registered.
EDS103 500 The dataset registered with ID The dataset is still registered in the ap
<datasetID> is not registered any plication but not accessible anymore.
more. Please unregister this dataset.
EDS104 404 The dataset <datasetID> does not No variable is found at the specified po
have any variable at position sition in the specified dataset.
<position>.
EDS105 403 The dataset <datasetID> cannot be The unregistered dataset must be de
deleted because it has dependencies : leted but it has dependencies.
<datasetID1, datasetID2,...>.
Please unregister the dependencies be
fore unregistering this dataset.
EDS106 400 The provided list of variables does not A list of variables has been provided,
contain <variable>. but it does not contain an existing data
set variable. Edit the list of variables.
EDS107 400 The <variable> variable was not The provided list of variables contains a
found in the dataset. name that does not match any actual
dataset variable. Edit the list of varia
bles.
EDS108 400 The <variable> variable is specified The storage type of a specified variable
with a <storage_type> storage type, does not match its actual representa
but is stored as tion in the database. Edit the list of vari
<actual_storage_type> in the data ables.
base.
EDS109 400 The <variable> variable is specified A variable should appear at most once
more than once. in the list describing variable proper
ties. Edit the list of variables.
EDS110 400 The variable <variable> has incom The specified combination of settings
patible storage (<storage_type>) either is not allowed or has no meaning.
and value (<value_type>) types. Edit the list of variables.
EDS111 400 Column names with blank characters The specified dataset contains one or
are not allowed in the datasets. The fol more columns with names containing
lowing columns have blank characters spaces. These datasets are not sup
in their names: ported.
[<column_name1>,...,<column_namen
>]

5.7.4 Job Access Error Messages (EJB)
EJB101 404 The <service> job <jobID> was not The specified job ID does not exist or
found. does not refer to the specified service.
5.7.5 Modeling Parameter Error Messages (EMO)
EMO108 400 "<targetColumn>" was identified as a The specified target is continuous so it

continuous target. You should not spec makes no sense to use a target key as
ify targetKey when the target is contin parameter.
uous.

6 Predictive Analytics Integrator Services
6.1 Service Description
This release allows you to train an Automated Analytics model on a dataset and to apply this model on a new
dataset.
End-users can create simple Automated Analytics models by specifying only a few settings. They can then run
these models on a specific set of data to produce predictive results. The Predictive Analytics Integrator
services rely on new concepts that describe the models to be managed:
Object Description
Catalog Catalogs are containers for predictive scenarios and datasets. They behave like folders in a
file system.
Predictive scenario Applications interact with predictive models through a predictive scenario.
Dataset A dataset is a reference to a physical data source, such as a database table or view.
Task A task is the object that you run in order to train and apply predictive models.
Model Models are containers for model versions.
Model version A model version represents a trained model. It contains a reference to a physical model
within the back-end system.
Remember
The predictive scenario is a static interface between the consuming application and the predictive
capabilities. It abstracts the concept of models and model versions away from the application developer.
This way, applications can interact with a predictive scenario without knowing anything about the physical
model behind it.
6.2 How the Service Works
Learn how objects work together by following typical end-user workflows.
If the predictive scenario does not exist
First, the user answers the business question by creating a predictive scenario without a signature, which is the
description of the input datasets and output results. Then, they have to create a Train task and provide certain
settings to generate a model and a model version. The user indicates if the model version is active when the

Predictive Analytics Integrator Services PUBLIC 101
task is finished. A model is created under the predictive scenario on which the task is performed. A model
version is then created under the new model and is assigned version 1. The model version attached to the
predictive scenario is used to create the signature automatically, based on the metadata extracted from the
physical model beneath. Metadata on the trained model are copied to the model version. Finally, the user
applies it to the input dataset. Output data is written into an SAP HANA database table so applications can
consume the data from that table directly.
If the predictive scenario exists
The user must browse the catalog to find the predictive scenario. If the predictive scenario already has a
signature defined, it is read-only at this point and then the model version added is used to validate the model
against the signature. No automatic extraction is done. If the validation fails, the model version is not added to
the scenario.
Remember
● The Train task works only with Automated Analytics models.
● The Apply task does not create a new model version. Apply is focused on data in and data out.
6.2.1 About Bindings
A predictive scenario is a logical entity that needs data accessed through an SAP HANA table or view in order
to train models and generate predictions. To this end, it is possible to bind a dataset to a predictive scenario for
use as the default when tasks are run. Default bindings can be overridden by input bindings set at the task level
between an input dataset and a task. The back-end system validates the binding against the signature of the
predictive scenario.
Related Information
Predictive Scenario [page 111]

Task [page 122]
6.2.2 About Validation
The back-end system validates the dataset that is bound to a predictive scenario to make sure it conforms to
the signature of the predictive scenario. Only conforming datasets can be bound to the corresponding
predictive scenario. A conforming dataset has column name and storage values identical to those of the
signature input structure.

102 PUBLIC Predictive Analytics Integrator Services
If a model version is created under a predictive scenario, then a validation step is run to ensure that the model
content conforms to the existing signature of the predictive scenario. Only conforming model versions can be
attached to the corresponding predictive scenario.
6.2.3 About Model Activation
Before an end user can run a task against a predictive scenario, the model version needs to be made active for
that predictive scenario. There are three ways to do this:
● Setting the AutoActivate parameter of the Train Task object to true before running it. The model
version created is activated automatically once the task is finished.
● Setting the Active parameter of the ModelVersion object to true once the task has run.
● Setting the ActiveModelVersion parameter of the PredictiveScenario object via the call
[PUT] /api/pai/PredictiveScenarios('GUID')/$links/ActiveModelVersion with the
reference to the model version in the request.
You can choose the method you prefer as they are equivalent to each other.
Related Information
Predictive Scenario [page 111]

Task [page 122]
Model Version [page 129]
6.3 OData REST API Quick Reference
The Predictive Analytics Integrator services allow an end user to create, consume, and manage predictive
models.
Overview
These services are a set of OData REST APIs that you use to integrate predictive analysis features into a cloud
application. This release allows you to train an Automated Analytics model on a dataset and to apply this model
on a new dataset.
Test these APIs directly in the SAP API Business Hub with the sample datasets described in Datasets
Available for SAP API Business Hub [page 164].
OData Version: 2.0
Root URI: /api/pai/

Service Metadata URI: /api/pai/$metadata
Permissions: sap.hana.pai::ExecutePAI
Common Headers
Common Request Headers
Header Required Description
Accept Yes application/json
Note
According to the OData specification, a call that returns an entity always returns the entity metadata
("d:"{ "__metadata": {...). To avoid returning metadata, add odatamedata=none to the Accept
request header: application/json;odatametadata=none.
Common Response Headers
Header Description
Accept application/json
Common Status and Error Codes
The service uses the common OData 2.0 response codes described in this table. Some specific codes are used
for request validation errors (400) and not found objects (404). For 500 error codes, a generic message is
returned and the exception is written to the logs.
Code Reason
200 OK. Indicates that a request has been received and processed successfully by a data service
and that the response body is not empty.
202 Accepted. Indicates that a batch request has been accepted for processing, but that the
processing has not been completed.
204 No Content. Indicates that a request has been received and processed successfully by a
data service and that the response does not include a response body.
400 Bad Request. Indicates that the payload, request headers, or request URI provided in a re
quest are not correctly formatted according to the syntax rules defined in this document.
404 Not Found. Indicates that a segment in the request URI's resource path does not map to an
existing resource in the data service. A data service may respond with a representation of an
empty collection of entities if the request URI addressed a collection of entities.
405 Method Not Allowed. Indicates that a request used an HTTP method not supported by the
resource identified by the request URI.

Code Reason
412 Precondition Failed. Indicates that one or more of the conditions specified in the request
headers evaluated to false.
500 Internal Server Error. Indicates that a request being processed by a data service encoun
tered an unexpected error during processing.
The following JSON response is returned in case of error:
{
"error": {
"code",
"message": {
"lang":"en",
"value"
}
}
}
where:
● code is the error code

● lang is the locale corresponding to the language of the error message
● value is the error message
Note
The same applies for asynchronous tasks, except that the message and code are written to the Message
property of the Task object.
Related Information
http://www.odata.org/documentation/odata-version-2-0/

6.3.1 Entity Data Model
The object that the application code deals with first is the PredictiveScenario. This object contains the
Task (Apply or Train) and the Model. The model does not represent the underlying model itself (predictive
model or pipeline), it is only a container for ModelVersion objects, which represent the actual underlying
models. The PredictiveScenario also references the active model version, if there is one.
The application code stores the end user datasets and the Apply results in the SAP HANA database. The model
version references the underlying model managed by the back-end system of the services and stored in SAP
HANA.
Properties
Each entity or object has a set of properties. Some of these properties are extracted from the underlying model
or created by the back-end system automatically, while others need to be provided by the application end user.
System-provided properties are read-only, while user-provided properties can be modified. The application
code does not have to set system-provided properties in a request, since most of them are actually extracted
from the model content. User-provided properties can be set either at object creation time only or at any time.

For example, the scenario type must be set in the request that creates the predictive scenario, whereas the
signature can be added later.
Containment Relationships
The model makes heavy use of containment relationships between many of the objects so that their lifecycles
are connected. When you delete the parent, all children are deleted automatically. So you don’t have to manage
each object individually. A containment relationship is identified by a navigation property. See the Usage
Scenarios [page 131] for examples.
Deep Insert
OData allows you to call a deep insert, which creates multiple objects at the same time by simply embedding
them inside each other. This is similar to what you get at query time when you use $expand. For example, you
can define a task directly inside the Tasks property of a PredictiveScenario and then pass the whole thing
in so you create both the PredictiveScenario and the child Task at the same time.
Resources
Resource Description Path
Catalog [page 108] Represents a container for PredictiveScenario and /Catalogs

Dataset objects. Catalogs can also contain other catalogs.
Predictive Scenario [page Represents a logical predictive model. /

111] PredictiveScenarios
Dataset [page 119] Represents a physical data source, such as an SAP HANA /Datasets
database table or view.
Task [page 122] Represents an operation performed by an application end /Tasks

user on predictive models, such as Train or Apply.
Model [page 127] Represents the physical model. Acts as a container for /Models
ModelVersion objects.
Model Version [page 129] Represents the physical trained model with all its informa /ModelVersions
tion (version, metadata, and metrics).
Common Properties
In addition to any standard OData properties, all the objects have the following properties in common.
Remember
In this document, the description of a property shows if it is provided by the system ('System' in 'From'
column) or can be input by the application end user ('User'). User-provided properties may or may not be
required in the POST request when creating the object ('No' in 'Required on POST' column). If a property set
by the end user cannot be modified, it is also mentioned in the description.

Property Description From Required on POST
GUID The unique identifier of the object. System
Used in API calls to specify a unique entity

within an entity set, for example /pai/
Catalogs('GUID').
The standard representation is a hyphen-sepa

rated hexadecimal string, such as 6c156b2d-
da98-4f83-80a2-62574e590e37.
Name The userspecified object name. User Yes
This name must be unique within the set of ob

jects that have the same parent. Must be be
tween 1 and 512 Unicode characters in length.
The '/' slash character is not allowed. Leading
and trailing spaces will be trimmed automati
cally and therefore will not contribute to charac
ter count.
Path The hierarchy path of an object. System
It is calculated dynamically from Name and

combined with the properties of all its ances
tors.
Type The object type, for example System

PredictiveScenario, Model, or
ModelVersion.
Description The userspecified description of the object. User No
Maximum 5000 Unicode characters. All charac

ters are allowed. Leading and trailing spaces will
be trimmed automatically and therefore will not
contribute to character count.
CreationTime The object creation date. System
Type is Edm.DateTime.
LastModificatio The last modification date of the object. System

nTime
A timestamp with the same format as
CreationTime.
6.3.2 Catalog
Represents a container for PredictiveScenario and Dataset objects.
Catalogs are a simple way to organize predictive scenarios and datasets. They behave like folders in a file
system. A Catalog has a name and optionally a reference to a parent Catalog. Each Catalog has a

maximum of one parent and any number of children (Catalog, PredictiveScenario, or Dataset objects).
If you delete a Catalog, all descendants of that Catalog will be deleted.
Resource Path:/Catalogs
Operations
CRUD Operations
HTTP Method Operation URI
POST Creates a catalog. /Catalogs
GET Retrieves a catalog specified by its unique ob /Catalogs('GUID')

ject reference.
PUT Updates a specific property of a catalog identi /Catalogs('GUID')/<property>/

fied by its unique object reference. $value
PATCH Updates properties of a catalog identified by its /Catalogs('GUID')

unique object reference.
DELETE Deletes a catalog specified by its unique object /Catalogs('GUID')

reference.
POST Creates a child catalog of a catalog. /Catalogs('GUID')/Catalogs
GET Retrieves a child catalog specified by its unique /Catalogs('GUID')/

object reference. Catalogs('GUID')
PUT Updates a specific property of a child catalog /Catalogs('GUID')/

identified by its unique object reference. Catalogs('GUID')/<property>/
$value
PATCH Updates properties of a child catalog identified /Catalogs('GUID')/

by its unique object reference. Catalogs('GUID')
DELETE Deletes a child catalog specified by its unique /Catalogs('GUID')/

object reference. Catalogs('GUID')
Properties
Remember

Property Data Type or En Description From Required on
tity Type POST
CatalogType String A free-form string that can be used to add User No

the application's own custom type infor
mation.
Types can be up to 64 Unicode characters

long. Leading and trailing spaces will be
trimmed automatically and therefore will
not contribute to character count.
Parent Catalog object The parent Catalog of the current ob User Yes
or null ject.
Only Catalog objects are allowed. If

omitted, the Catalog is a root object.
Note
The target entity set, in which an entity
will be created, will determine the pa
rent. POST /Catalogs results in a
null Parent (root object) whereas
POST /Catalogs('GUID')/
Catalogs sets the entity with GUID
identifier as parent.
Catalogs Array of The list of child Catalog objects of the User No

Catalog objects current object
Datasets Array of The list of child Dataset objects of the User No

Dataset objects current object
PredictiveSc Array of The list of child PredictiveScenario User No

enarios PredictiveSc objects of the current object
enario objects
Example
Here's a Catalog object, as it can be returned by a GET request:
{
"d": {
"__metadata": {
"id": "http://<server>:<port>/api/pai/
Catalogs('29eb9468-58c8-431d-9f71-27951e6860bb')",
"uri": "http://<server>:<port>/api/pai/
Catalogs('29eb9468-58c8-431d-9f71-27951e6860bb')",
"type": "com.sap.aa.ii.backend.ODataCatalog"
},
"CatalogType": "DemoFolder",
"Type": "Catalog",
"CreationTime": "2016-05-26T17:01:26.233",
"Description": "",
"GUID": "29eb9468-58c8-431d-9f71-27951e6860bb",
"LastModificationTime": "2016-05-26T17:01:26.233",
"Name": "MyCatalog",
"Path": "MyCatalog",

"Catalogs": {
"__deferred": {
Catalogs('29eb9468-58c8-431d-9f71-27951e6860bb')/Catalogs"
}
},
"Datasets": {
"__deferred": {
Catalogs('29eb9468-58c8-431d-9f71-27951e6860bb')/Datasets"
}
},
"Parent": {
"__deferred": {
Catalogs('29eb9468-58c8-431d-9f71-27951e6860bb')/Parent"
}
},
"PredictiveScenarios": {
"__deferred": {
Catalogs('29eb9468-58c8-431d-9f71-27951e6860bb')/PredictiveScenarios"
}
}
}
}
Related Information
OData REST API Quick Reference [page 103]
6.3.3 Predictive Scenario
Represents a logical predictive model.
A PredictiveScenario is the interface through which an application can interact with predictive models. A
PredictiveScenario can be child of a Catalog or a root object by itself.
A predictive scenario has a signature, which describes the input datasets and output results. Only models and
datasets conforming to this signature can be used in the predictive scenario. The real physical model will be
dynamically selected at runtime by resolving the predictive scenario into a particular model version. The
signature will never change during the lifespan of the predictive scenario. It assures you that the predictive
scenario stays the same even if the model implementation changes behind the scenes.
Resource Path: /PredictiveScenarios
Operations
CRUD Operations

POST Creates a logical predictive model. /PredictiveScenarios
GET Retrieves a predictive scenario specified by its /PredictiveScenarios('GUID')

PUT Updates a specific property of a predictive sce /PredictiveScenarios('GUID')/

nario identified by its unique object reference. <property>/$value
PATCH Updates properties of a predictive scenario /PredictiveScenarios('GUID')

identified by its unique object reference.
DELETE Deletes a predictive scenario specified by its /PredictiveScenarios('GUID')

Properties
Remember

tity Type POST
Parent Catalog object The parent Catalog of the current ob User No
or null ject.

omitted, the PredictiveScenario is
a root object.
ScenarioType String The logical model type. User Yes
Possible values are Regression and

Classification.
Signature Object The description of the input datasets and System/User (op No
[page 113] output results that make up the interface tional)
of a model.

tity Type POST
Bindings [page Object Bindings between database tables or User No

115] views and objects at task processing time.
Binding is done by object name.
Possible bindings are:
● Set on a predictive scenario and used

as default bindings
● Set on a task
● Set on both predictive scenario and a
task. The task binding overrides the
predictive scenario binding.
Models Array of Model The list of child Model objects of the cur User No
objects rent PredictiveScenario.
Use this property to add models to a pre

dictive scenario.
ActiveModelV Modelversion The specific physical model attached to User No

ersion object or null the current PredictiveScenario.
Null if there is no active ModelVersion.
The Apply task does not work without an

active model version. You can activate the
model version either by specifying
AutoActivate on the Train task or by
activating the ModelVersion later on
with a separate call (Active to true).
See About Model Activation [page 103].
Table 84: Signature

tity Type POST
Inputs Array of objects The variables of the input datasets re User No
quired by the model.
The array must contain at least one object

to be valid. This information is used to vali
date input datasets that are bound to the
current PredictiveScenario.
Note
This release only accepts an array of
size 1 (one input).

tity Type POST
Outputs Array of objects The variables of the output datasets gen User No
erated by the model when an Apply task is
run.

to be valid.
Table 85: Inputs or Outputs

tity Type POST
Name String The dataset logical name. User No
It can be any Unicode string up to 128

characters in length. It is used as an iden
tifier to reference this particular dataset at
binding time.
Description String The free-form text to describe the dataset User No

in a more readable way.
It can contain any string up to a maximum

length of 5000 Unicode characters.
Structure Array of objects The variable descriptions. User No

to be valid.
Table 86: Structure

tity Type POST
Name String For inputs, the name of the variable in the User No
model. For outputs, the name of the col
umn in the Apply output table.
It can contain any Unicode characters up

to 127 characters in length. It must be
unique within Structure.
Note
Name is important for validation pur
poses.
Storage String The variable storage type. User No
It must match the storage type in the da

taset and in the physical model.

tity Type POST
Type String The semantic type of the variable, used to User No

describe the role that the variable plays in
the underlying predictive model.
For inputs, possible values are Key and

Target. The target value size is lim
ited to 500 characters.
For outputs, possible values are

ApplyInfo, Key, Target,
Prediction, and Support.
ApplyInfo indicates variables that were

implicitly added by the back-end system
in order to, for example, disambiguate re
sults from multiple task runs in the same
output table.
Description String A free-form text used to describe the vari User No

able in a more readable way.
It can contain any string up to a maximum

length of 5000 Unicode characters.
Table 87: Bindings

tity Type POST
Inputs Array of objects The reference to the input dataset. User No
Outputs Array of objects The physical location where the data User No
should be stored when the Apply task is
run.
If omitted, the service generates the out

put table.
Table 88: Inputs

tity Type POST
Name String The name defined in User No

Signature.Inputs.
This is the target of the binding.
Reference Dataset object The URI reference to the Dataset object User No
to be used as input.
This is the source of the binding.

Table 89: Outputs
tity Type POST
Name String The name of the output dataset defined in User No

Signature.Outputs.
This is the target of the binding.
Location Object The physical location of the SAP HANA ta User No
ble or view containing the data.
This is the source of the binding.
Table 90: Location

tity Type POST
Schema String The SAP HANA schema User Yes
TableName String The name of the SAP HANA table or view. User Yes
Once set, it cannot be modified.
Example
Here's a PredictiveScenario object without default binding, as it can be returned by a GET request:
{
"__metadata":{
"id":"/api/pai/PredictiveScenarios('6c156b2d-
da98-4f83-80a2-62574e590e37')"
},
"GUID":"6c156b2d-da98-4f83-80a2-62574e590e37",
"Name":"FraudsterDetector",
"Parent":"/api/pai/Catalogs('8358096b-039e-47d9-84d0-f30a0ddb4ba2')",
"Path":"MyFunctionalArea/FraudsterDetector",
"Type":"PredictiveScenario",
"Description":"Find the persons who might lie regarding their age",
"CreationTime":"2016-05-26T17:01:26.233",
"LastModificationTime":"2016-05-26T17:01:26.233",
"ScenarioType":"Regression",
"Signature":{
"Inputs":[
{
"Name":"inputDataset",
"Description":"Structure of input dataset expected by the
predictive model",
"Structure":[
{
"Name":"id",
"Storage":"Integer",
"Type":"Key"
},
{
"Name":"age",
"Type":"Target"
},
{
"Name":"workclass",
"Storage":"String(16)"
},
{

"Name":"fnlwgt",
"Storage":"Integer"
},
{
"Name":"education",
},
{
"Name":"education-num",
"Storage":"TinyInteger"
},
{
"Name":"marital-status",
},
{
"Name":"occupation",
},
{
"Name":"relationship",
},
{
"Name":"race",
},
{
"Name":"sex",
},
{
"Name":"capital-gain",
"Storage":"Integer"
},
{
"Name":"capital-loss",
"Storage":"SmallInteger"
},
{
"Name":"hours-per-week",
},
{
"Name":"native-country",
},
{
"Name":"class",
}
]
}
],
"Outputs":[
{
"Name":"applyOutDataset",
"Description":"Structure of the results generated when executing
the predictive scenario",
"Structure":[
{
"Name":"id",
"Type":"Key"
},
{
"Name":"age",

"Type":"Target"
},
{
"Name":"rr_age",
"Storage":"Double",
"Type":"Prediction"
},
{
"Name":"bar_rr_age",
"Storage":"Double",
"Type":"Support"
},
{
"Name":"outlier_rr_age",
"Storage":"Double",
"Type":"Support"
},
{
"Name":"RCN_A_Mean_1_rr_age",
"Storage":"String(32)",
"Type":"Support"
},
{
"Name":"RCV_A_Mean_1_rr_age",
"Type":"Support"
},
{
"Name":"RCN_B_Mean_1_rr_age",
"Type":"Support"
},
{
"Name":"RCV_B_Mean_1_rr_age",
"Type":"Support"
},
{
"Name":"PAI.ApplyId",
"Type":"ApplyInfo"
},
{
"Name":"PAI.Timestamp",
"Storage":"TimeStamp",
"Type":"ApplyInfo"
}
]
}
]
},
"Bindings":{
"Inputs":[
]
},
"ActiveModelVersion":"/api/pai/ModelVersions('27f91587-dbe3-4b1d-
a4a7-9926247428b3')",
"Models":[
{
"uri":"/api/pai/Models('f21511b7-d7a8-46ff-a6f1-85e94a433d8c')"
},
{
"uri":"/api/pai/Models('4298c848-b012-473d-a60b-4e1206e7e83f')"
}
]
}

Related Information
6.3.4 Dataset
Represents a physical input dataset.
A Dataset is a reference to a physical data source, such as a database table or view. A Dataset can be the
child of a Catalog or a root object by itself.
A dataset can be bound to a predictive scenario for use as input when performing tasks. The back-end system
ensures that only datasets conforming to the signature of the predictive scenario can be bound to that
predictive scenario. A Dataset can be used by multiple PredictiveScenario objects.
Resource Path: /Datasets
Operations
CRUD Operations
POST Creates a dataset. /Datasets
GET Retrieves a dataset specified by its object refer /Datasets('GUID')

ence.
PUT Updates a specific property of a dataset identi /Datasets('GUID')/<property>/

fied by its object reference. $value
PATCH Updates properties of a dataset identified by its /Datasets('GUID')

object reference.
DELETE Deletes a dataset specified by its object refer /Datasets('GUID')

ence.
Properties
Remember

tity Type POST
Parent Catalog object The parent Catalog object of the cur User No
or null rent object.

omitted, the Dataset is a root object.
Location Object The physical location of the SAP HANA ta User Yes
ble or view containing the data.
Location has two properties Schema and

TableName.
Once set, it cannot be modified.
Columns Array of objects The variable descriptions that correspond System

to the columns of an SAP HANA database
table or view.
Table 91: Location

tity Type POST
Schema String The SAP HANA schema. User Yes
The predictive service DB user must have

access to this schema.
TableName String The name of the SAP HANA table or view. User Yes
Table 92: Columns

tity Type POST
Name String The name of the variable column in the ta System
ble or view.
Storage String The physical storage type of the variable System

in the table or view.
Example
Here's a Dataset object, as it can be returned by a GET request:
{
"__metadata":{
"id":"/api/pai/Datasets('b0bcd522-3728-4deb-9f33-ad1580ab1ca5')"
},
"GUID":"b0bcd522-3728-4deb-9f33-ad1580ab1ca5",
"Name":"DATA_SCHEMA_CENSUS",
"Parent":"/api/pai/Catalogs('8358096b-039e-47d9-84d0-f30a0ddb4ba2')",
"Path":"MyFunctionalArea/DATA_SCHEMA_CENSUS",
"Type":"Dataset",
"Description":"Example Dataset",
"CreationTime":"2016-05-26T17:01:26.233",
"Location":{
"Schema":"DATA_SCHEMA",

"TableName":"CENSUS"
},
"Columns":[
{
"Name":"id",
"Storage":"Integer"
},
{
"Name":"age",
"Storage":"Integer"
},
{
"Name":"workclass",
},
{
"Name":"fnlwgt",
"Storage":"Integer"
},
{
"Name":"education",
},
{
},
{
},
{
},
{
},
{
"Name":"race",
},
{
"Name":"sex",
},
{
"Storage":"Integer"
},
{
},
{
},
{
},
{
"Name":"class",
}
]

}
Related Information
6.3.5 Task
Represents the operation to perform on predictive models.
Task objects are children of PredictiveScenario objects. A Task is deleted when the
PredictiveScenario is deleted.
Tasks are run against PredictiveScenario objects. The logical predictive scenario is resolved into a physical
model version when the Apply task is run.
Tasks normally run asynchronously in the background. If the application code knows that a task will be fast-
running and wants to wait for the operation to complete, it can mark the task as synchronous.
Remember
Possible operations in this release are Apply and Train.
Resource Path: /Tasks
Operations
CRUD Operations
POST Performs an operation on predictive /Tasks

models, such as Apply or Train.
GET Retrieves a task specified by its object /Tasks('GUID')

reference.
PUT Updates a specific property of a task /Tasks('GUID')/<property>/$value

identified by its object reference.
PATCH Updates properties of a task identified /Tasks('GUID')

by its object reference.
DELETE Deletes a task specified by its object /Tasks('GUID')

reference.

Properties
Remember

tity Type POST
TaskStatus String The processing state of the task. System
Possible values are Pending,

Processing, Success, or
Failure. If Failure, error mes
sages will be written to Messages.
ModelVersion ModelVersion The reference to the actual System

object ModelVersion object used to proc
ess this task.
Parent PredictiveSc The parent PredictiveScenario User Yes

enario object of the current Task.
This defines the predictive scenario

against which the task will run. Once
created, the Task object cannot be
moved.
TaskType String The task type. User Yes
Possible values are Apply and Train.
Bindings Object The bindings between the dataset and User No

the predictive scenario signature.
These bindings override the default

bindings specified in the predictive sce
nario. Bindings are done at dataset level
in the input or outputs.
Synchronous Boolean Indicates whether the task will run syn User No
chronously with its creation.
If omitted, the task runs asynchro

nously.
Definition Object User No

Remember
Train task type only.
The settings for the Automated Analyt

ics engine to train a new model.

tity Type POST
Messages Array of objects The error code and message returned if System
the task fails (TaskStatus is
Failure).
AutoActivate Boolean User No

Remember
Train task type only.
Indicates whether the model version is

activated when the Train task is fin
ished. Default is false.
Table 93: Definition

tity Type POST
Target String The reference to the target variable of User Yes

the input dataset.
This is the name of a dataset column.

Mandatory in the definition. The target
variable value is 500 characters maxi
mum.
TargetKey String User No

Remember
Classification scenario type
only.
The value of a category from the

Target variable that is used as the
positive target when training the model
If omitted, the back-end system selects

the value that occurs least frequently in
the estimation data.
Key Array of strings The references to existing variables User No

that compose the primary key in the in
put dataset.
ApplyOutput Object Settings affecting the output the model User No

generates at Apply time.

Table 94: ApplyOutput
tity Type POST
Probability Boolean User No

Remember
only.
Indicates whether the predicted value is

output as a probability for a Classifica
tion model. Default is true.
PredictedVal Boolean User No

ue Remember
Regression scenario type only.
Indicates whether the estimated pre

dictive value is output for a Regression
model. This is the default output, but it
can be suppressed by setting this prop
erty to false.
Score Boolean User No

Remember
only.
Indicates whether the predicted value is

output as a score for a Classification
model. Default is false.
Percentile Boolean Indicates whether the predicted value is User No

output as a percentile for a Classifica
tion model. Default is false.
Reasons Object Configures the number of Reasons col User No

umns the user would like to see.
Reasons are always calculated accord

ing to the Mean contribution.
Table 95: Reasons

tity Type POST
Negative Integer This optional integer subproperty User No

specifies the top n reasons below the
mean contribution to generate. There
will be an additional column in the Ap
ply output for each one (variable and
value). Default is 0, maximum is 100.

tity Type POST
Positive Integer This optional integer subproperty User No

specifies the top n reasons above the
mean contribution to generate. There
will be two additional columns in the
Apply output for each one (variable and
value). Default is 0, maximum is 100.
Example
Train Task
Here's a Train Task object, as it can be returned by a GET request:
{
"__metadata": {
"id": "/api/pai/Tasks('7d60b5ac-caec-4b61-95f1-1a3a4b55cfef')"
},
"GUID" : "7d60b5ac-caec-4b61-95f1-1a3a4b55cfef",
"Name" : "FraudsterDetector 2016-11-20T09:00:32.153",
"Parent" : "/api/pai/PredictiveScenarios('6c156b2d-
da98-4f83-80a2-62574e590e37')",
"Path" : "FraudsterDetector/FraudsterDetector 2016-05-26T17:01:26.233",
"Type" : "Task",
"Description" : "Train a new classification model",
"CreationTime" : "2016-11-20T09:00:32.153",
"LastModificationTime" : "2016-11-20T09:00:32.153",
"TaskType" : "Train",
"Definition": {
"Target" : "class",
"Key" : ["id"],
"AutoActivate": true,
"ApplyOutput" : {
"Reasons" : {
"Positive" : 3,
"Negative" : 1
}
}
},
"Bindings" : {
"Inputs" : [
{
"Name" : "inputDataset",
"Reference" : "/api/pai/Datasets('b0bcd522-3728-4deb-9f33-
ad1580ab1ca5')"
}
]
},
"TaskStatus" : "Processing"
}
Example
Apply Task
Here's an Apply Task object with overriding bindings, as it can be returned by a GET request:
{
"__metadata": {
"id": "/api/pai/Tasks('69b5cfb4-8b4b-4428-bb5f-766d055798cd')"

},
"GUID" : "69b5cfb4-8b4b-4428-bb5f-766d055798cd",
"Name" : "FraudsterDetector 2016-05-26T17:01:26.233",
da98-4f83-80a2-62574e590e37')",
"Path" : "FraudsterDetector/FraudsterDetector 2016-05-26T17:01:26.233",
"Type" : "Task",
"Description" : "Training a new classification model.",
"CreationTime" : "2016-05-26T17:01:26.233",
"TaskType" : "Apply",
"ModelVersion" : "/api/pai/ModelVersions('27f91587-dbe3-4b1d-
a4a7-9926247428b3')"
"Bindings" : {
"Inputs" : [
{
"Name" : "inputDataset",
"Reference" : "/api/pai/Datasets('b0bcd522-3728-4deb-9f33-
ad1580ab1ca5')"
}
],
"Outputs" : [
{
"Name" : "applyOutDataset",
"Location" : {
"Schema" : "OUTPUT_SCHEMA",
"TableName" : "APPLY_OUT_TABLE"
}
}
]
},
"TaskStatus" : "Processing"
}
Related Information
6.3.6 Model
Represents a physical model.
The Model object can be viewed as a container for child ModelVersion objects.
Models cannot be created by themselves. They must always have at least one model version, and most of the
metadata is extracted from the underlying model content.
Resource Path: /Models
Operations
CRUD Operations

GET Retrieves the model specified by its ob /Models('GUID')

ject reference.
PUT Updates a specific property of the /Models('GUID')/<property>/$value

model identified by its object reference.
PATCH Updates properties of the model identi /Models('GUID')

fied by its object reference.
DELETE Deletes the model specified by its ob /Models('GUID')

ject reference.
Properties
Remember

tity Type POST
ModelType String The native model type extracted from the System
physical model.
For example,
Kxen.RobustRegression.
ModelVersion Array of The references to the model versions at System

s ModelVersion tached to a model.
objects
Parent PredictiveSc The parent PredictiveScenario ob User Yes

enario object ject of the current model.
All Model objects must have a parent

PredictiveScenario. Once created,
a Model can never be moved to another
Example
Here's a Model object, as it can be returned by a GET request:
{
"__metadata": {
"id": "/api/pai/Models('f21511b7-d7a8-46ff-a6f1-85e94a433d8c')"
},
"GUID" : "f21511b7-d7a8-46ff-a6f1-85e94a433d8c",
"Name" : "K2R_Census_Age",

da98-4f83-80a2-62574e590e37')",
"Path" : "MyFunctionalArea/FraudsterDetector/K2R_Census_Age",
"Type" : "Model",
"Description" : "Baseline model for outliers detection",
"CreationTime" : "2016-05-26T17:40:45.333Z",
"ModelType" : "Kxen.RobustRegression",
"ModelVersions" : [
{ "uri" : "/api/pai/ModelVersions('27f91587-dbe3-4b1d-
a4a7-9926247428b3')" },
{ "uri" : "/api/pai/ModelVersions('48cb23cf-4565-4d63-a68a-
eb6edd94d50d')" }
]
}
Related Information
6.3.7 Model Version
Represents a real, trained predictive model.
A ModelVersion object references a real physical model stored in SAP HANA. It is attached to a
PredictiveScenario. ModelVersion objects are children of Model objects.
Additionally, the ModelVersion object contains a version number and some model metrics. It can be marked
as "active" and then applications can access this active version from the ActiveModelVersion property of a
Resource Path: /ModelVersions
Operations
CRUD Operations
GET Retrieves a model version specified by /ModelVersions('GUID')

its object reference.
PUT Updates a specific property of a model /ModelVersions('GUID')/<property>/$value

version identified by its object refer
ence.
PATCH Updates properties of a model version /ModelVersions('GUID')

specified by its object reference.

DELETE Deletes a model version specified by its /ModelVersions('GUID')

object reference.
Properties
Remember

tity Type POST
Parent Model object The parent Model of the current User Yes
ModelVersion in which the model
version will live.
All ModelVersion objects must have

a parent Model. Once created, a
ModelVersion can never be moved.
Version Number The model version number. System
A Train task creates a new Model and

ModelVersion objects, and
Version number is 1..
Active Boolean Indicates whether this model version is User

the active model version.
There can be only one active model ver

sion per predictive scenario.
Metrics Array of strings A list of numeric metrics used to de System

scribe model performance, such as the
quality or the error level of the model.
Table 96: Metrics

Property Type Description From Required on
POST
Name String The metric name. System
Value Number The numeric value of the metric. System

Property Type Description From Required on
POST
Flag String Indicates the meaning of the metric to System

consuming applications.
For example, HigherIsBetter to in

dicate that a larger number is more de
sirable than a smaller number.
Example
Here's a ModelVersion object, as it can be returned by a GET request:
{
"__metadata": {
"id": "/api/pai/ModelVersions('27f91587-dbe3-4b1d-a4a7-9926247428b3')"
},
"GUID" : "27f91587-dbe3-4b1d-a4a7-9926247428b3",
"Name" : "K2R_Census_age_Version_3",
"Parent" : "/api/pai/Models('f21511b7-d7a8-46ff-a6f1-85e94a433d8c')",
"Path" : "MyFunctionalArea/FraudsterDetector/K2R_Census_Age/
K2R_Census_age_Version_3",
"Type" : "ModelVersion",
"Description" : "Target = \"age\", NumberOfReasonCode=3",
"Version" : 1,
"CreationTime" : "2016-05-26T17:40:45.333",
"Active" : true,
"Metrics" : [
{
"Name" : "predictivePower",
"Value" : 0.6275,
"Flag" : "HigherIsBetter"
}, {
"Name" : "predictionConfidence",
"Value" : 0.99,
}
]
}
Related Information
6.4 Usage Scenarios
The following scenarios illustrate a typical usage of the services to create and consume a predictive model.

You will see the request that the end user needs to construct is much simpler than the corresponding entity
once it is persisted in the back-end system. Actually, the service generates as many properties as possible, so
that the end user does not have to provide them.
Note
In these scenarios, the call responses show deserialized complex properties.
Related Information
Service Description [page 101]

Create, Train, and Apply [page 132]
Create, Train, and Apply (Deep Insert) [page 144]
Dealing with Complex Properties [page 158]
6.4.1 Create, Train, and Apply
In this scenario, the end user answers a business question by performing a predictive analysis on their
customer data stored on SAP HANA.
Step Description
Create a predictive scenario without model Creating a Predictive Scenario [page 132]
Create a dataset to train the model Creating a Dataset [page 134]
Create a Train task to initialize the predictive scenario with Training a Model [page 136]
an automated model
Apply the predictive scenario on a dataset stored in an SAP Applying the Model [page 141]
HANA database table and get the results
6.4.1.1 Creating a Predictive Scenario
You create a predictive scenario with minimal information. There is no underlying physical model.
Request
URI: /api/pai/PredictiveScenarios
HTTP Method: POST

Request body:
{
"Name" : "CustomerClassification",
"Description" : "Identify people with gain over 40K USD",
"ScenarioType" : "Classification"
}
Response
The response contains properties generated by the service plus information provided by the request. Since
there is no underlying model from which to extract model metadata, it does not contain any signature.
{ "d": {
"__metadata": {
"id": "https://<server>:<port>/api/pai/PredictiveScenarios('9ed39768-
c0fb-4085-abfb-54a6ae6f88c6')",
"uri": "https://<server>:<port>/api/pai/PredictiveScenarios('9ed39768-
c0fb-4085-abfb-54a6ae6f88c6')",
"type": "com.sap.aa.ii.backend.ODataPredictiveScenario"
},
"Bindings": "",
"ScenarioType": "Classification",
"Signature": "",
"Type": "PredictiveScenario",
"CreationTime": "2016-12-28T10:48:47.329",
"Description": "Identify people with gain over 40K USD",
"GUID": "9ed39768-c0fb-4085-abfb-54a6ae6f88c6",
"LastModificationTime": "2016-12-28T10:48:47.329",
"Name": "CustomerClassification",
"Path": "CustomerClassification",
"ActiveModelVersion": {
"__deferred": {
c0fb-4085-abfb-54a6ae6f88c6')/ActiveModelVersion"
}
},
"Models": {
"__deferred": {
c0fb-4085-abfb-54a6ae6f88c6')/Models"
}
},
"Parent": {
"__deferred": {
"uri":"https://<server>:<port>/api/pai/PredictiveScenarios('9ed39768-
c0fb-4085-abfb-54a6ae6f88c6')/Parent"
}
},
"Tasks": {
"__deferred": {
c0fb-4085-abfb-54a6ae6f88c6')/Tasks"
}
}
}
}
Note
ActiveModelVersion, Models, Parent, and Tasks are navigation properties between the predictive
scenario and its children or parent. They are defined in the service metadata. According to the OData

specification, the __deferred property contains a link to the object when this one is not asked to be
returned as a whole object.
6.4.1.2 Creating a Dataset
You create a dataset with minimal information, that is, the location of the dataset in SAP HANA.
Note
The CENSUS table is a sample dataset that the database user can read (SELECT right). CENSUS will be used
to train and apply the model. SERVICE_TEST is the schema within the same SAP HANA instance as the
deployed predictive service.
Request
URI: /api/pai/Datasets
HTTP Method: POST
Request body:
{
"Name": "Census",
"Description": "Census demo dataset",
"Location": { "Schema": "SERVICE_TEST", "TableName": "CENSUS" }
}
Response
The response contains properties generated by the service, plus information provided by the request. The
service returns the list of input variables from the dataset of which table name and schema have been passed
in the request. The service has also generated a specific GUID for this dataset.
{
"d":{
"__metadata":{
"id":"https://<server>:<port>/api/pai/Datasets('3f4ba129-87b2-4cc6-99dd-
d07b37ec377b')",
"uri":"https://<server>:<port>/api/pai/
Datasets('3f4ba129-87b2-4cc6-99dd-d07b37ec377b')",
"type":"com.sap.aa.ii.backend.ODataDataset"
},
"Location":{
"Schema":"SERVICE_TEST",
},
"Type":"Dataset",
"Columns":[

{
"Name":"id",
"Storage":"Integer"
},
{
"Name":"age",
},
{
"Name":"workclass",
},
{
"Name":"fnlwgt",
"Storage":"Integer"
},
{
"Name":"education",
},
{
},
{
},
{
},
{
},
{
"Name":"race",
},
{
"Name":"sex",
},
{
"Storage":"Integer"
},
{
},
{
},
{
},
{
"Name":"class",
}
],
"CreationTime":"2016-12-20T15:41:52.011",
"Description":"Census demo dataset",
"GUID":"bad17c49-1053-4854-9b0e-1d48163069b9",

"Name":"Census",
"Path":"Census"
}
}
6.4.1.3 Training a Model
Create a train task with the input binding on the table used for train and a given target variable.
Caution
When providing the Input Dataset for the training Task, if the dataset contains a DECIMAL column, the
precision and the scale must be included in the column type definition. Make sure to provide both
arguments at all times to avoid errors during the creation of the ModelVersion. For more details see: SAP
HANA SQL and System Views Reference.
Request
URI: /api/pai/PredictiveScenarios('9ed39768-c0fb-4085-abfb-54a6ae6f88c6')/Tasks
HTTP Method: POST
Request body:
An input dataset is bound to the task by a reference in bindings. Definition specifies the target variable to be
used when training the model.
{
"Name":"TrainTask",
"TaskType":"Train",
"Definition":{
"Target":"class"
},
"Bindings":{
"Inputs":[
{
"Reference":"/api/pai/Datasets('3f4ba129-87b2-4cc6-99dd-
d07b37ec377b')"
}
]
}
}
Response
The response contains properties generated by the service plus information provided by the request. The task
is still ongoing, as shown by TaskStatus and asynchronous by default, as shown by Synchronous to null.

The user has to wait for the task to finish to get a model version attached to a model, and a model attached to
the predictive scenario.
{
"d":{
"__metadata":{
"id":"https://<server>:<port>/api/pai/Tasks('01ee5873-30ba-4c8f-8210-
b08dc4932c9b')",
"uri":"https://<server>:<port>/api/pai/Tasks('01ee5873-30ba-4c8f-8210-
b08dc4932c9b')",
"type":"com.sap.aa.ii.backend.ODataTask"
},
"Bindings":{
"Inputs":[
{
"Mapping":null,
"Reference":"/api/pai/
Datasets('bad17c49-1053-4854-9b0e-1d48163069b9')"
}
]
},
"Definition":{
"Target":"class"
},
"Messages":"[]",
"Name":"TrainTask",
"TaskStatus":"Pending",
"TaskType":"Train",
"Type":"Task",
"Synchronous":null,
"CreationTime":"2016-05-26T17:01:26.233",
"Description":"",
"GUID":"01ee5873-30ba-4c8f-8210-b08dc4932c9b",
"Path":"CustomerClassification/TrainTask",
"ModelVersion":{
"__deferred":{
Tasks('01ee5873-30ba-4c8f-8210-b08dc4932c9b')/ModelVersion"
}
},
"Parent":{
"__deferred":{
Tasks('01ee5873-30ba-4c8f-8210-b08dc4932c9b')/Parent"
}
}
}
}
Note
ModelVersion and Parent are navigation properties between the task and its children or parent. They are
defined in the service metadata. According to the OData specification, the __deferred property contains a
link to the object when this one is not asked to be returned as a whole object.

Checking the Task Status
Request
URI: /api/pai/Tasks('69b5cfb4-8b4b-4428-bb5f-766d055798cd')/TaskStatus
HTTP Method: GET
Request body: none
Response
{
"d":{
"TaskStatus":"Success"
}
}
Activating the Model Version
The user activates the model version by setting a specific URI corresponding to the actual model version to the
ActiveModelVersion property.
Request
URI: /api/pai/PredictiveScenarios('9ed39768-c0fb-4085-abfb-54a6ae6f88c6')/$links/
ActiveModelVersion
HTTP Method: PUT
Request body:
{
"uri" : "http://<server>:<port>/api/pai/ModelVersions('97ad0c02-ee9d-485c-b120-
ac41c0f8cc85')"
}
Response
Response code: HTTP 204

Checking the Model Version
The user can check the ActiveModelVersion property to see if the model has been activated successfully.
This is an optional request.
Request
URI: /api/pai/PredictiveScenarios('9ed39768-c0fb-4085-abfb-54a6ae6f88c6')?
$expand=ActiveModelVersion
HTTP Method: GET
Request body: none
Response
The object requested and returned is the PredictiveScenario. The $expand parameter set to the
ActiveModelVersion property allows you to get a response that also contains the whole active
ModelVersion object. The signature has been created from the underlying model (active model version) for
the current predictive scenario. The system has computed some metrics when the model has been trained
against the input dataset, and the service has returned them.
{
"d":{
"__metadata":{
"id":"https://<server>:<port>/api/pai/PredictiveScenarios('9ed39768-
c0fb-4085-abfb-54a6ae6f88c6')",
"uri":"https://<server>:<port>/api/pai/PredictiveScenarios('9ed39768-
c0fb-4085-abfb-54a6ae6f88c6')",
"type":"com.sap.aa.ii.backend.ODataPredictiveScenario"
},
"Bindings":"",
"ScenarioType":"Classification",
"Signature":{
"Inputs":[
{
"Description":"",
"Structure":[
{
"Name":"id",
"Type":"Key"
},
{
...
},
{
"Name":"class",
"Storage":"SmallInteger",
"Type":"Target"
}
]
}

],
"Outputs":[
{
"Name":"outputDataset",
"Description":"",
"Structure":[
{
"Name":"id",
"Type":"Key"
},
{
...
},
{
"Name":"class",
"Type":"Predicted"
}
]
}
]
},
"CreationTime":"2016-12-20T15:38:36.645Z",
"Description":"Identify people with gain over 40K USD",
"GUID":"91f25488-2bac-4624-ae3b-2ef1ec1031c2",
"Name":"CustomerClassification",
"Path":"CustomerClassification",
"ActiveModelVersion":{
"__metadata":{
"id":"https://<server>:<port>/api/pai/ModelVersions('97ad0c02-
ee9d-485c-b120-ac41c0f8cc85')",
"uri":"https://<server>:<port>/api/pai/ModelVersions('97ad0c02-
ee9d-485c-b120-ac41c0f8cc85')",
"type":"com.sap.aa.ii.backend.ODataModelVersion"
},
"Metrics" : [
{
"Value" : 0.6275,
},
{
"Value" : 0.99,
}
],
"Type":"ModelVersion",
"Version":1,
"Active":true,
"CreationTime":"2016-12-20T15:40:45.375",
"GUID":"97ad0c02-ee9d-485c-b120-ac41c0f8cc85",
"Name":"bd2ecb93-511b-449d-855a-5f102373f395",
"Path":"CustomerClassification/TrainTask/
bd2ecb93-511b-449d-855a-5f102373f395",
"Parent":{
"__deferred":{
ee9d-485c-b120-ac41c0f8cc85')/Parent"
}
},
"Tasks":{
"__deferred":{

ee9d-485c-b120-ac41c0f8cc85')/Tasks"
}
}
}
}
}
Note
Parent and Tasks are navigation properties between the model version and its children or parent. They are
6.4.1.4 Applying the Model
The predictive scenario has an underlying model. Now you create an Apply task to predict values for the target
variable on a new dataset. Here the same dataset is used.
Note
CENSUS_RESULT is the table that will receive the result of the Apply task. The predictive service DB user
must have rights to the table specified in the output binding for the Apply.
Request
HTTP Method: POST
Request body:
You specify the output details in the bindings.
{
"Name":"ApplyTask",
"TaskType":"Apply",
"Bindings":{
"Inputs":[
{
d07b37ec377b')"
}
],
"Outputs":[
{
"Location":{
"TableName":"CENSUS_RESULT"
}
}

]
}
}
Response
The response contains properties generated by the service plus information provided by the request.
Definition specifies the target variable to be used when applying the model. The task is still ongoing, as
shown by TaskStatus and asynchronous by default, as shown by Synchronous to null.
{
"d":{
"__metadata":{
b08dc4932c9b')",
b08dc4932c9b')",
},
"Bindings":{
"Inputs":[
{
"Mapping":null,
}
],
"Outputs":[
{
"Location":{
}
}
]
},
"Messages":"[]",
"Name":"ApplyTask",
"TaskType":"Apply",
"Type":"Task",
"Synchronous":null,
"CreationTime":"2016-05-26T17:01:29.233",
"Description":"",
"Path":"CustomerClassification/ApplyTask",
"ModelVersion":{
"__deferred":{
}
},
"Parent":{
"__deferred":{
}
}
}

}
Note
Request
URI: /api/pai/Tasks('01ee5873-30ba-4c8f-8210-b08dc4932c9b')/TaskStatus/$value
HTTP Method: GET
Request body: none
Response
"Success"
Getting the Results

As specified when creating the apply task, the application has to query the SERVICE_TEST/CENSUS_RESULT
to get the apply results. The column generated is proba_rr_class.
Select * from SERVICE_TEST/CENSUS_RESULT;

6.4.2 Create, Train, and Apply (Deep Insert)
This scenario illustrates the concept of deep insert in OData through the creation of a predictive scenario and a
Train task together in one request.
Step Description
Create a dataset to train the model Creating a Dataset [page 144]
Create a predictive scenario with a Train task to initialize the Creating a Predictive Scenario with a Train Task [page 146]
predictive scenario with an automated model
Apply the predictive scenario on a dataset stored in an SAP Applying the Model [page 155]
HANA database table and get the results
6.4.2.1 Creating a Dataset
You create a dataset with minimal information, that is, the location of the dataset in SAP HANA.
Note
The CENSUS table is a sample dataset that the database user can read (SELECT right). CENSUS will be used
to train and apply the model. SERVICE_TEST is the schema within the same SAP HANA instance as the
deployed predictive service.
Request
URI: /api/pai/Datasets
HTTP Method: POST
Request body:
{
"Name": "Census",
"Description": "Census demo dataset",
"Location": { "Schema": "SERVICE_TEST", "TableName": "CENSUS" }
}
Response
The response contains properties generated by the service, plus information provided by the request. The
service returns the list of input variables from the dataset of which table name and schema have been passed
in the request. The service has also generated a specific GUID for this dataset.

"d":{
"__metadata":{
"id":"https://<server>:<port>/api/pai/Datasets('3f4ba129-87b2-4cc6-99dd-
d07b37ec377b')",
Datasets('3f4ba129-87b2-4cc6-99dd-d07b37ec377b')",
"type":"com.sap.aa.ii.backend.ODataDataset"
},
"Location":{
},
"Type":"Dataset",
"Columns":[
{
"Name":"id",
"Storage":"Integer"
},
{
"Name":"age",
},
{
"Name":"workclass",
},
{
"Name":"fnlwgt",
"Storage":"Integer"
},
{
"Name":"education",
},
{
},
{
},
{
},
{
},
{
"Name":"race",
},
{
"Name":"sex",
},
{
"Storage":"Integer"
},
{
},
{

},
{
},
{
"Name":"class",
}
],
"CreationTime":"2016-12-20T15:41:52.011",
"Description":"Census demo dataset",
"GUID":"bad17c49-1053-4854-9b0e-1d48163069b9",
"Name":"Census",
"Path":"Census"
}
}
6.4.2.2 Creating a Predictive Scenario with a Train Task
Add task properties to the request along with predictive scenario details.
Request
URI: /api/pai/PredictiveScenarios
HTTP Method: POST
Request body:
An input dataset is bound to the task by a reference in bindings. Definition specifies the target variable to be
used when training the model.
{
"Tasks":[
{
"Name":"TrainTask",
"TaskType":"Train",
"Definition":{
"Target":"class"
},
"Bindings":{
"Inputs":[
{
d07b37ec377b')"
}
]
}
}
]

}
Response
Predictive scenario and task have been created but the signature is still empty. The task is still ongoing, as
shown by TaskStatus and asynchronous by default, as shown by Synchronous to null. The user has to wait
for the task to finish to get a model version attached to a model, and a model attached to the predictive
scenario.
{
"d":{
"__metadata":{
"id":"https://<server>:<port>/api/pai/
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')",
},
"Bindings":"",
"Signature":"",
"CreationTime":"2016-05-26T17:01:26.233",
"GUID":"437a5303-2512-4c16-852b-190659474096",
"__deferred":{
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')/ActiveModelVersion"
}
},
"Models":{
"__deferred":{
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')/Models"
}
},
"Parent":{
"__deferred":{
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')/Parent"
}
},
"Tasks":{
"results":[
{
"__metadata":{
Tasks('ef390129-2cc1-40ea-b2e6-002301353ee3')",
Tasks('ef390129-2cc1-40ea-b2e6-002301353ee3')",
},
"Bindings":{
"Inputs":[
{
"Reference":"/api/pai/Datasets('2a07adaa-403f-44e9-bda4-
a6e9af9fe297')",

"Mapping":null
}
],
"Outputs":[
]
},
"Definition":{
"Target":"class",
"Weight":null
},
"Messages":"[]",
"Name":"TrainTask",
"TaskType":"Train",
"Type":"Task",
"Synchronous":null,
"CreationTime":"2016-05-26T17:01:26.233",
"Description":"",
"GUID":"ef390129-2cc1-40ea-b2e6-002301353ee3",
"Path":"CustomerClassification/TrainTask",
"ModelVersion":{
"__deferred":{
Tasks('ef390129-2cc1-40ea-b2e6-002301353ee3')/ModelVersion"
}
},
"Parent":{
"__deferred":{
Tasks('ef390129-2cc1-40ea-b2e6-002301353ee3')/Parent"
}
}
}
]
}
}
}
This mode is asynchronous by default. Check the task status. The predictive scenario is returned with a
signature once the task is finished.
Request
URI: /api/pai/PredictiveScenarios('9ed39768-c0fb-4085-abfb-54a6ae6f88c6')/
Tasks('ef390129-2cc1-40ea-b2e6-002301353ee3')
HTTP Method: GET
Request body: none

Response
{
"d":{
"results":[
{
"Definition":{
"Target":"Class"
},
"Bindings":{
"Inputs":[
{
"Mapping":null,
"Reference":"/api/pai/Datasets('b03f57a4-373d-4b03-b709-
eca0f577ed0d')"
}
]
},
"Messages":"",
"Name":"TrainTask",
"TaskType":"Apply",
"Type":"Task",
"Synchronous":null,
"CreationTime":"2016-05-26T17:01:26.233",
"Description":"",
"GUID":"1a4ef494-2115-4c7f-96f7-a79fd983f62f",
"Path":"CustomerClassification/ApplyTask"
}
]
}
}
Activating the Model Version
The user activates the model version by setting a specific URI corresponding to the actual model version to the
ActiveModelVersion property.
Request
URI: /api/pai/PredictiveScenarios('9ed39768-c0fb-4085-abfb-54a6ae6f88c6')/$links/
ActiveModelVersion
HTTP Method: PUT
Request body:
{
"uri" : "http://<server>:<port>/api/pai/ModelVersions('6ccbef39-a9f5-4f74-
a453-6fb0103fafa5')"
}

Response
Response code: HTTP 204
Checking the Model Version
The user can check the ActiveModelVersion property to see if the model has been activated successfully.
This is an optional request.
Request
URI: /api/pai/PredictiveScenario('9ed39768-c0fb-4085-abfb-54a6ae6f88c6')?
$expand=ActiveModelVersion
HTTP Method: GET
Request body: none
Response
The $expand parameter set to the ActiveModelVersion property allows you to get the response that
contains the whole active ModelVersion object. The signature has been created from the underlying model
(active model version) for the current predictive scenario.
{
"d":{
"__metadata":{
},
"Bindings":"",
"Signature":{
"Inputs":[
{
"Description":"",
"Structure":[
{
"Name":"id",
"Type":"Input"
},
{
"Name":"age",
"Storage":"TinyInteger",
"Type":"Input"

},
{
"Name":"workclass",
"Type":"Input"
},
{
"Name":"fnlwgt",
"Type":"Input"
},
{
"Name":"education",
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Name":"race",
"Type":"Input"
},
{
"Name":"sex",
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Name":"class",

"Type":"Target"
}
]
}
],
"Outputs":[
{
"Description":"",
"Structure":[
{
"Name":"id",
"Type":"Input"
},
{
"Name":"age",
"Type":"Input"
},
{
"Name":"workclass",
"Type":"Input"
},
{
"Name":"fnlwgt",
"Type":"Input"
},
{
"Name":"education",
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Name":"race",
"Type":"Input"
},
{
"Name":"sex",
"Type":"Input"
},
{

"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Type":"Input"
},
{
"Name":"class",
"Type":"Target"
},
{
"Name":"rr_class",
"Storage":"Double",
"Type":"Predicted"
},
{
"Name":"PAI.ApplyId",
"Type":"ApplyInfo"
},
{
"Name":"PAI.Timestamp",
"Storage":"TimeStamp",
"Type":"ApplyInfo"
}
]
}
]
},
"CreationTime":"2016-05-26T17:01:26.233",
"GUID":"437a5303-2512-4c16-852b-190659474096",
"__metadata":{
"id":"https://<server>:<port>/api/pai/ModelVersions('6ccbef39-
a9f5-4f74-a453-6fb0103fafa5')",
"uri":"https://<server>:<port>/api/pai/ModelVersions('6ccbef39-
a9f5-4f74-a453-6fb0103fafa5')",
"type":"com.sap.aa.ii.backend.ODataModelVersion"
},
"Metrics" : [
{
"Value" : 0.6275,
},
{
"Value" : 0.99,
}

],
"Type":"ModelVersion",
"Version":1,
"Active":true,
"CreationTime":"2016-05-26T17:01:26.233",
"Description":"",
"GUID":"6ccbef39-a9f5-4f74-a453-6fb0103fafa5",
"Name":"53e12dd3-08f7-41cb-bb6f-d90f01110739",
"Path":"CustomerClassification/TrainTask/53e12dd3-08f7-41cb-bb6f-
d90f01110739",
"Parent":{
"__deferred":{
a9f5-4f74-a453-6fb0103fafa5')/Parent"
}
},
"Tasks":{
"__deferred":{
a9f5-4f74-a453-6fb0103fafa5')/Tasks"
}
}
},
"Models":{
"__deferred":{
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')/Models"
}
},
"Parent":{
"__deferred":{
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')/Parent"
}
},
"Tasks":{
"__deferred":{
PredictiveScenarios('437a5303-2512-4c16-852b-190659474096')/Tasks"
}
}
}
}
Note
Parent, Models, and Tasks are navigation properties between OData objects. They are defined in the
service metadata. For example:
<NavigationProperty Name="Parent"
Relationship="com.sap.aa.ii.backend.ODataModelVersion_Parent_ODataModel_Version
s" FromRole="Parent" ToRole="Versions"/>
<AssociationSet Name="ODataModelVersion_Parent_ODataModel_Versions"
Association="com.sap.aa.ii.backend.ODataModelVersion_Parent_ODataModel_Versions
">
<End EntitySet="Models" Role="Versions"/>
<End EntitySet="ModelVersions" Role="Parent"/>
</AssociationSet>
According to the OData specification, the __deferred property contains a link to the object when this one
is not asked to be returned as a whole object.

6.4.2.3 Applying the Model
The predictive scenario has an underlying model. Now you create an Apply task to predict values for the target
variable on a new dataset. Here the same dataset is used.
Note
CENSUS_RESULT is the table that will receive the result of the Apply task. The predictive service DB user
must have rights to the table specified in the output binding for the Apply.
Request
HTTP Method: POST
Request body:
You specify the output details in the bindings.
{
"Name":"ApplyTask",
"TaskType":"Apply",
"Bindings":{
"Inputs":[
{
d07b37ec377b')"
}
],
"Outputs":[
{
"Location":{
}
}
]
}
}
Response
The response contains properties generated by the service plus information provided by the request.
Definition specifies the target variable to be used when applying the model. The task is still ongoing, as
shown by TaskStatus and asynchronous by default, as shown by Synchronous to null.
{
"d":{
"__metadata":{

b08dc4932c9b')",
b08dc4932c9b')",
},
"Bindings":{
"Inputs":[
{
"Mapping":null,
}
],
"Outputs":[
{
"Location":{
}
}
]
},
"Messages":"[]",
"Name":"ApplyTask",
"TaskType":"Apply",
"Type":"Task",
"Synchronous":null,
"CreationTime":"2016-05-26T17:01:29.233",
"Description":"",
"Path":"CustomerClassification/ApplyTask",
"ModelVersion":{
"__deferred":{
}
},
"Parent":{
"__deferred":{
}
}
}
}
Note

Request
URI: /api/pai/Tasks('01ee5873-30ba-4c8f-8210-b08dc4932c9b')/TaskStatus/$value
HTTP Method: GET
Request body: none
Response
"Success"
Getting the Results
As specified when creating the apply task, the application has to query the SERVICE_TEST/CENSUS_RESULT
to get the apply results. The column generated is proba_rr_class.
Select * from SERVICE_TEST/CENSUS_RESULT;

6.5 Dealing with Complex Properties
You serialize or deserialize JSON strings of complex properties when handling model entities.
The entity data model does not use Edm:ComplexType to represent complex properties. Only simple
properties based on primitive types like Edm.String, Edm.Boolean, or Edm.DateTime are used. Complex
properties are represented as Edm.String properties containing serialized JSON, which gives more flexibility
to express data structures. You can identify these complex properties in the service metadata because they are
qualified with the attribute content="json". For example:
<EntityType Name="ODataDataset">
<Key>
<PropertyRef Name="GUID"/>
</Key>
<Property Name="Location" Type="Edm.String" content="json"/>
<Property Name="Type" Type="Edm.String" sap:default="Dataset"
xmlns:sap="http://www.sap.com/Protocols/SAPData"/>
<Property Name="Variables" Type="Edm.String" content="json"/>
<Property Name="CreationTime" Type="Edm.DateTime"/>
<Property Name="Description" Type="Edm.String" sap:default=""
xmlns:sap="http://www.sap.com/Protocols/SAPData"/>
<Property Name="GUID" Type="Edm.String"/>
<Property Name="LastModificationTime" Type="Edm.DateTime"/>
<Property Name="Name" Type="Edm.String" sap:default="" xmlns:sap="http://
www.sap.com/Protocols/SAPData"/>
<Property Name="Path" Type="Edm.String"/>
<NavigationProperty Name="Parent"
Relationship="com.sap.aa.ii.backend.ODataDataset_Parent_ODataCatalog_Datasets"
FromRole="Parent" ToRole="Datasets"/>
</EntityType>
Instances of the Dataset entity will contain a Location property whose value is a serialized JSON string:
{
"d": {
...,
"Location": "{
\"Schema\":\"APL_SAMPLES\",
\"TableName\":\"CENSUS\"
}"
...,
}
}
You can easily parse the serialized JSON content into a languagespecific data structure using standard
libraries.
JavaScript
In JavaScript, use the following functions:
● JSON.parse(string) to produce a JavaScript object from a JSON string

● JSON.stringify(object) to produce a serialized string from a JavaScript object

The Location JavaScript object will be as follows:
{
...
"Location": {
"Schema": "APL_SAMPLES",
"TableName": "CENSUS"
}
...
}
Java
In Java, you can use the open-source Jackson library to handle the mapping between JSON and Java
structures. Use the ObjectMapper object to map to and from generic JsonNode objects:
ObjectMapper mapper = new ObjectMapper();

// ...from JSON to Java
JsonNode actualObj = mapper.readTree(jsonString);
// ...from Java to JSON
String newJsonString = mapper. writeValueAsString(actualObj)
You can also have Java classes representing the types to be more specific:
class Location {
private String schema;
private String tableName;
// standard getters and setters
}
ObjectMapper mapper = new ObjectMapper();
// ...from JSON to Java instance of the Location class
Location loc = mapper.readValue(json, Location.class);
// ...from Java to JSON
String newJsonString = mapper.writeValueAsString(loc);

7 Data Protection and Privacy
7.1 Introduction
Governments place legal requirements on industry to protect data and privacy. We provide features and
functions to help you meet these requirements.
Note
SAP does not provide legal advice in any form. SAP software supports data protection compliance by
providing security features and data protection-relevant functions, such as blocking and deletion of personal
data. In many cases, compliance with applicable data protection and privacy laws is not covered by a
product feature. Furthermore, this information should not be taken as advice or a recommendation
regarding additional features that would be required in specific IT environments. Decisions related to data
protection must be made on a case-by-case basis, taking into consideration the given system landscape and
the applicable legal requirements. Definitions and other terms used in this documentation are not taken
from a specific legal source.
7.2 Glossary
Term Definition
Blocking A method of restricting access to data for which the primary

business purpose has ended.
Business purpose A legal, contractual, or in other form justified reason for the
processing of personal data. The assumption is that any pur
pose has an end that is usually already defined when the
purpose starts.
Consent The action of the data subject confirming that the usage of
his or her personal data shall be allowed for a given purpose.
A consent functionality allows the storage of a consent re
cord in relation to a specific purpose and shows if a data
subject has granted, withdrawn, or denied consent.
Deletion Deletion of personal data so that the data is no longer avail

able.

160 PUBLIC Data Protection and Privacy
Term Definition
End of business Date where the business with a data subject ends, for exam
ple the order is completed, the subscription is canceled, or
the last bill is settled.
End of purpose (EoP) End of purpose and start of blocking period. The point in
time, when the primary processing purpose ends (for exam
ple contract is fulfilled).
End of purpose (EoP) check A method of identifying the point in time for a data set when
the processing of personal data is no longer required for the
primary business purpose. After the EoP has been reached,
the data is blocked and can only be accessed by users with
special authorization (for example, tax auditors).
Personal data Any information relating to an identified or identifiable natu

ral person ("data subject"). An identifiable natural person is
one who can be identified, directly or indirectly, in particular
by reference to an identifier such as a name, an identifica
tion number, location data, an online identifier or to one or
more factors specific to the physical, physiological, genetic,
mental, economic, cultural, or social identity of that natural
person
Purpose The information that specifies the reason and the goal for
the processing of a specific set of personal data. As a rule,
the purpose references the relevant legal basis for the proc
essing of personal data.
Residence period The period of time between the end of business and the end
of purpose (EoP) for a data set during which the data re
mains in the database and can be used in case of subse
quent processes related to the original purpose. At the end
of the longest configured residence period, the data is
blocked or deleted. The residence period is part of the over
all retention period.
Retention period The period of time between the end of the last business ac
tivity involving a specific object (for example, a business
partner) and the deletion of the corresponding data, subject
to applicable laws. The retention period is a combination of
the residence period and the blocking period.

Data Protection and Privacy PUBLIC 161
Term Definition
Sensitive personal data A category of personal data that usually includes the follow
ing type of information:
● Special categories of personal data, such as data re

vealing racial or ethnic origin, political opinions, reli
gious or philosophical beliefs, trade union membership,
genetic data, biometric data, data concerning health or
sex life or sexual orientation.
● Personal data subject to professional secrecy
● Personal data relating to criminal or administrative of
fenses
● Personal data concerning insurances and bank or credit
card accounts
Where-used check (WUC) A process designed to ensure data integrity in the case of
potential blocking of business partner data. An application's
where-used check (WUC) determines if there is any depend
ent data for a certain business partner in the database. If de
pendent data exists, this means the data is still required for
business activities. Therefore, the blocking of business part
ners referenced in the data is prevented.
7.3 Read-Access Logging
The SAP Predictive service does not manage read-access logging. Read-access logging should be put in place
in the data-owning system.
7.4 Information Report
The SAP Predictive service does not handle information report. Any data inquiries should be directed to the
data-owning system.
7.5 Erasure
The SAP Predictive service does not delete any data. The deletion of data should be handled by the data-
owning system.

162 PUBLIC Data Protection and Privacy
7.6 Change Log
The SAP Predictive service does not modify any data. Change log should be managed in the data-owning
system.
7.7 User Consent
The SAP Predictive service does not collect any data. User consent should be managed by the data-owning
system.

Data Protection and Privacy PUBLIC 163
8 Datasets Available for SAP API Business
Hub
A description of the sample datasets available in SAP HANA to be used with SAP Predictive service.
The table specifies which services are worth testing with the datasets.
Dataset Service Description Schema Name Table Name
CENSUS Clustering, Key In Excerpt from the American Census Bu APL_SAMPLES CENSUS_500
fluencers, Outliers, reau database, completed in 1994 and
Scoring Equation, by Barry Becker. CENSUS_1000
and What-if
It contains 14 characteristics of an indi
vidual extracted from a census dataset
associated to an indicator equal to 1,
when the individual earned more than
fifty thousand dollars the previous year,
else 0. In the dataset, the name of this
indicator is class.
There are 2 datasets, one with 500

rows and one with 1000 rows.
See Introduction to Sample Files in Au

tomated Analytics User Guides and Sce
narios (Modeler, then Classification/
Regression) on the SAP Help Portal.
CashFlows Forecasts Contains historical cash flow data from APL_SAMPLES CASHFLOWS
2016 and 23 other indicators.
This allows you to do a time series anal

ysis to predict the evolution of the cash
flow on a given horizon.
There are 272 rows in this dataset.

narios (Modeler, then Time Series) on
the SAP Help Portal.

164 PUBLIC Datasets Available for SAP API Business Hub
Dataset Service Description Schema Name Table Name
Customer Trans Recommendation Contains historical transactions of APL_SAMPLES CUST_TRANSAC

actions products purchased by customers. TIONS
Customers are identified by their
UserID and products by the name of
the items purchased.
There are 9996 transactions in this da

taset. There are 2873 users for 39 prod
ucts.

narios (Modeler, then Association
Rules) on the SAP Help Portal.

Datasets Available for SAP API Business Hub PUBLIC 165
9 Archive - Release Notes for SAP
Predictive Service 2017
25 September 2017 - SAP Predictive Service
Announcement
The service name is now SAP Predictive service.
Fix
Documentation
The configuration tasks have been updated. See Configuration Tasks [page 13].
Enhancement
Documentation
The version numbers of the predictive service have been added to the What's New. See What's New [page 6].
26 July 2017 - Predictive Service
Enhancement
All business services
When creating a job, the input parameter of the response is now formatted as a JSON object instead of a string. See
Job Response Body Parameters [page 86].
Enhancement
Key Influencers
End-users can now get the variables that are correlated to each other, with their coefficient of correlation. See the
correlatedVariables property in Response Body Parameters [page 54].
Enhancement
Error codes and messages
EXX121 is a new message related to incompatibility between input parameters. See General Service Parameter Error
Messages (EXX) [page 97].

166 PUBLIC Archive - Release Notes for SAP Predictive Service 2017
Enhancement
Documentation
An important note has been added to the Clustering APIs documentation to explain the link between the view export
method and the modelSQLExportEnabled input parameter. See Request Body Parameters [page 27].
Fix
Documentation
A correction has been made to the data source binding procedure. Only <default> can be used as data source name. See
Bind the Data Source [page 15].
19 June 2017 - Predictive Service
New
The new collection of services Predictive Analytics Integrator Services is available to add model management tasks to
your application. See Service Description [page 101].
6 June 2017 - Predictive Service
Enhancement
Clustering
End-users can now specify the distance used to measure the proximity of two data points. It's enabled through the
distance input parameter. See Request Body Parameters [page 27].
Enhancement
Forecasts
End-users can now:
● Specify the maximum lag to consider when forecasts are computed. It's enabled through the maxLag input param
eter. See Request Body Parameters [page 46].
● Get the MAPE indicator for each horizon. It's output in the mapePerHorizon property under
modelPerformance. See Response Body Parameters [page 49].

Archive - Release Notes for SAP Predictive Service 2017 PUBLIC 167
22 May 2017 - Predictive Service
Enhancement
Dataset
End-users can now specify the schema and the table of the dataset in SAP HANA separately in the request. It's enabled
through the location input parameter. hanaURL has been deprecated. See Register an SAP HANA Table as Dataset
[page 33].
9 May 2017 - Predictive Service
Enhancement
Scoring Equation
End-users can now choose the type of output generated by the scoring equation (predicted value or probability). It's en
abled through the predictionOutputType input parameter. See Request Body Parameters [page 78].
24 April 2017 - Predictive Service
Enhancement
All services
The variableDescription parameter has been deprecated from the request body of the APIs. From now on, end-
users must use the Dataset APIs to specify the variable descriptions (Register an SAP HANA Table as Dataset [page 33])
or to modify them (Modify the Variable Description [page 42]).
Enhancement
Outliers and Scoring Equation
End-users can now set the key of the target variable through the TargetKey input parameter. See Request Body Pa
rameters [page 59] (outliers) and Request Body Parameters [page 78] (scoring equation).
New
Documentation
The documentation now specifies that referenceDate must follow the ISO 8601 format in the Forecasts API request.
See Request Body Parameters [page 46].

10 April 2017 - Predictive Service
New
Clustering
A new Clustering service is available and provides a set of APIs that allow end-users to segment an input dataset into
clusters and to get segmentation results into an SAP HANA database table or view. See Clustering APIs [page 26].
Enhancement
Outliers
End-users can now enable autoselection of variables through the autoSelection input parameter. See Request
Body Parameters [page 59].
New
Documentation
A first usage scenario has been added to the documentation. It describes an end-to-end clustering process. See Creat
ing Clusters with Either High or Low Target Rate [page 87].
13 March 2017 - Predictive Service
Enhancement
Forecasts
● End-users can now specify the modeling technique used to generate forecasts: the default Automated Analytics
technique, the exponential smoothing, or the linear regression. It's enabled through the forecastMethod input
parameter of the APIs [POST] /api/analytics/forecast/sync and [POST] /api/analytics/
forecast.
● End-users can now specify the cycle length in the case of the smoothing technique. It's enabled through the
smoothingCycleLength input parameter of the same APIs.
See Request Body Parameters [page 46].
Enhancement
Dataset
End-users can now specify if a variable column is a component of the primary key. See Modify the Variable Description
[page 42].

New
SAP API Business Hub
You can now explore, test, and consume the predictive service through the SAP API Business Hub .
13 February 2017 - Predictive Service
New
SAP HANA
The predictive service supports SAP HANA 1.0 SPS12.
Enhancement
Dataset
End-users can now modify the value types of the variables. It's enabled through the new API [POST] /api/
analytics/dataset/<datasetID>/variables/update. See Modify the Variable Description [page 42].
Enhancement
● HTTP code of EDS101 has changed from 500 to 400.

● EDS111 is a new message related to blank characters not allowed in dataset column names.
16 January 2017 - Predictive Service
New
SAP HANA APL
The predictive service supports SAP HANA APL 3.1.
Enhancement
Forecasts
● End-users can now get the past data with both predicted and real values of each data point. It's enabled through the
numberOfPastValuesInOutput input parameter. See Request Body Parameters [page 46].
● End-users can now get the definition of the trend, cycles, and fluctuation features found in the data and used by the
underlying time series model to generate forecasts. It's available in the modelInformation output property.
See Response Body Parameters [page 49].

Enhancement
Dataset
When registering a dataset, end-users can now provide the description of the variables contained in the dataset. The
specified description is used whenever the associated dataset is used with the predictive service. See Register an SAP
HANA Table as Dataset [page 33].
New
EDS106 to EDS110 are new messages related to errors in the list of variables provided in the dataset service request. See
Dataset Service Error Messages (EDS) [page 99].

Important Disclaimers and Legal Information
Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.
Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as
"sales person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun
does not exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.
Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any
damages caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for
transparency (see: https://help.sap.com/viewer/disclaimer).

172 PUBLIC Important Disclaimers and Legal Information
Important Disclaimers and Legal Information PUBLIC 173
go.sap.com/registration/
contact.html
© 2018 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any
form or for any purpose without the express permission of SAP SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software vendors.
National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company products and services
are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein
should be construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks of
SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see https://www.sap.com/corporate/en/legal/copyright.html
for additional trademark information and notices.

SAP Predictive Service User Guide

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

SAP Predictive Service User Guide

Загружено:

Авторское право:

Доступные форматы

Developer Guide PUBLIC