Tell us what you think

We want to create the best possible experience for our learners. Your feedback helps us to improve the experience for everyone.

Deploying Models

Objective

After completing this lesson, you will be able to deploy modeling content to the runtime enviroment

The SAP HANA Deployment Infrastructure

The SAP HANA Deployment Infrastructure (HDI) is a set of services that allows the deployment of database objects into isolated HDI containers.

HDI containers are simply database schemas, but they include additional features such as a dedicated owner of the container plus metadata to manage their database objects. Think of a container as a smart schema.

The objects included in the containers are defined in the HDB modules of your project, using source files and during deployment, the runtime objects are created and added to the container.

HDI takes care of dependency management and determines the order of deployment; it also provides support for upgrading existing runtime artifacts when their corresponding design-time artifacts are modified.

One key concept of HDI containers is the fact that the entire lifecycle (creation, modification, and deletion) of database objects is performed exclusively by the HDI. Therefore, you aren't able to directly create database artifacts, such as tables or views, with Data Definition Language (DDL) statements using SQL.

Data Sources for Calculation Views

When you develop calculation views, the data sources you choose must exist as design-time files in the container of your HDB module. So they must be of one of the following types:

"Real" database objects (table, view, table function, virtual tables, and so on) existing inside the container and having a corresponding design-time file in the HDB module
Synonyms referencing database objects located in any other schema than the container itself. You’ll learn about synonyms later on.

Caution

A calculation view that refers to a data source that was created directly using SQL in your container (so, without a source-file) can't be built. The build fails and issues an error message, such as:

Code snippet

The file requires "db://HA300::TABLE_SQL" which is not provided by any file

Expand

Key Properties of HDI Containers

A container is create automatically when you deploy your database module for the first time.
A container generates a database schema the moment that a container is first created.
Database objects are deployed into that schema.
Source file definitions must be written in a schema-free way.
Direct references to objects outside your container aren't allowed. You must use synonyms.

HDI Container Configuration File

Within each HDB module of a project you'll find a very important and mandatory file that exists under the src folder with the suffix: .hdiconfig. This is the HDI container configuration file that is used to bind the design-time files of your project to the corresponding installed build plug-in.

Screen capture of the configuration file for the container. It contains the required plugins, and in this example the minimum plug-in version that applies to all plug-ins.

Without the build plug-in it isn't possible to deploy the runtime objects from the design-time files. This configuration file directs each source file in your project to the correct build plug-in.

Usually there's only one .hdiconfig file in an HDB module, and this must be located in the src folder of the HDB module. This file contains a list of all bindings for all source file types.

The minimum_feature_version entry of this file is there to prevent building your HDB module objects with a version of HANA Cloud that is lower than what is specified and/or what your code requires. For example, if you've designed and tested your HDB module with version 1004 of the build plug-ins, this will not deploy on an SAP HANA Cloud instance where version 1002 is in place.

Inside the container configuration file you'll find, for each source file type, two entries:

Suffix name, for example, "hdbcalculationview"
Plug-in name, for example, "com.sap.hana.di.calculationview"

It’s very important to remember that when you import a project into your landscape, it brings with it its own .hdiconfig file that refers to the feature version that was used when it was first developed. If you then plan to update the source file using newer features of SAP HANA (for example, you want to add a new feature to a calculation view that just became available with the newer version of SAP HANA) you will not see the new feature in the source editor if the .hdiconfig file hasn't been adjusted to use the later feature version.

Caution

The HDI container configuration file is an unnamed file and must only consist of the suffix .hdiconfig. If you try to add a name, the build of the .hdiconfig file will fail. Leave it as it is.

The SAP HANA PROJECTS View

In SAP Business Application Studio, when a project includes an SAP HANA DB module, a dedicated view SAP HANA PROJECTS is available (alongside the Explorer view).

The SAP HANA Projects view/panel is the materialization of the HDB modules defined in your projects. The upper part represents the folder structure of the HDB module. The root element corresponds to the path to the HDB module in the project. To create the runtime objects inside the connected HDI container schema, you can execute a deployment. This deployment can be triggered at different levels: a single file, a folder, or the entire HDB module.

Note

You can't manipulate (move, copy, delete, and so on) your design-time files from the SAP HANA PROJECTS view, but you can open them in their respective editor.

In the file structure, Pending Deployment identifies where a deployment is required for new or modified files. For deleted design-time files, you need to activate the run-time object deletion by deploying the folder that contained them.

The lower part represents the Database Connections between the HDB module and the HDI containers or services providing access to external resources.

A project with an SAP HANA Database module needs at least a corresponding HDI Container to deploy its runtime objects. This is what is shown in the image, The SAP HANA PROJECTS View.

In the connection part, you can bind an existing HDB module to a new or existing HDI container. You can also add new connections (for example to another container), and

The Database Explorer

From SAP Business Application Studio, you can launch the Database Explorer application to view the database artifacts (tables, views, procedures, column views) of one or several containers.

When you do this, even if you're logged on to SAP Business Application Studio with your usual SAP Business Application Studio user, access to the container is done by a technical SBSS (Service Broker Security Support) user that is created transparently when you add the container to the Database Explorer. This technical user interacts with the database objects on your behalf, for example, to view the content of a table or preview the data of a calculation view.

If your container consumes data from an external schema, the technical user must also be granted authorizations to the external schema objects, for example, to view the data of an external table referenced by a synonym. You'll learn more about this in the unit, Security in SAP HANA Modeling.

Deploying Modeling Objects

During development, you need to create or update the runtime objects from the design-time objects inside the container schema. For that, you use the Deploy function available in the SAP HANA PROJECTS view.

Deploying relies on the HDI container service (a Cloud Foundry service), which manages the interaction between SAP Business Application Studio, the HANA Deployment Infrastructure, and in turn the SAP HANA database.

When you bind an HDB module to an HDI container service, this binding creates the corresponding container schema, if it does not exist. After that, design-time objects can be deployed to the HDI container.

Structure of Building Modeling Content

When you deploy a HANA database module, the HDI deployer populates the HDI container, that is a schema located in the SAP HANA cloud database, with the runtime objects defined in the module.

A deploy operation can be executed at the following levels of a project structure:

An entire HDB module
A subfolder of the HDB module
One or several individual objects

Note

The deploy operation described above shouldn't be confused with what is also called Deploy in Cloud Foundry. In Cloud Foundry, the deploy command (cf deploy) applies to an entire application (for example, an entire MTA, including potentially more than just the HDB module). It’s used mainly when you want to transport and deploy/activate your project to another environment. For example, from the DEV to the QA or PROD environment.

Regardless of what you deploy (HDB module, subfolder, or single object), there's always an end-to-end dependency check applied to each object that is part of the build scope. So, even if you build a single object, there will be a recursive check of all the objects it references to make sure these objects already exist as runtime objects or are defined in a design-time object and built at the same time.

Deploy Errors

When you deploy models defined in an HDB module, you might come across different issues, which are described in the log that you can consult in the console. Some are related to the dependency checks we've just discussed. Others have to do with the consistency of design-time objects (for example, the namespace settings of design-time folders). Another classical build error is when two different design-time files provide a definition for the same runtime object.

Here's a list of frequent root causes for deploy errors.

Most Common Errors During Build Operations

The definition of an object on which another object depends isn't provided, or it's provided but this object hasn't been deployed yet.
The definition of a runtime object is provided by several design-time files.
There's a namespace inconsistency between the content of a design-time file and the namespace property of the folder in which it's located.
The service to access external schemas isn't defined or not available in the target space.
The synonyms for external schema access aren't deployed yet.
There's an object-specific design error.
For example, no measure is defined in a Cube calculation view.
There's an inconsistency between the object you build and a referenced object.
For example, there's a mismatch in a column name between two objects with a dependency.

Putting a Design File Aside to Work Around Build Issues

When a Calculation View cannot be built for whatever reason, it generally prevents the build of its containing folder and any upper folder. There are several approaches you can use to solve this issue temporarily and go on working on the rest of your models, without losing completely the existing design-time file.

Export the Calculation View to a safe place, and then delete the Calculation View from your workspace.
When executing the build, the removed Calculation View won't cause any issue. When you want to resume working on this view, you just need to import it back to its original location.
Add .txt to the design-time file. For example, SALES.hdbcalculationview will become SALES.hdbcalculationview.txt.
In this scenario, you don't remove the file from the workspace, but modify its extension so that it's (temporarily) not considered as a Calculation View design-time file but a plain text file. No specific check is performed on a .txt file upon build, so it will have the same effect as removing the file, but it's then much easier to undo: you just need to remove the additional .txt extension.

Next lesson