hana-cloud-native

SAP HANA Cloud Native — HDI Best Practices

Primary reference: https://help.sap.com/docs/hana-cloud-database HDI (Deployment Infrastructure) Reference: https://help.sap.com/docs/HANA_CLOUD_DATABASE/c2cc2e43458d4abda6788049c58143dc SQLScript Reference: https://help.sap.com/docs/HANA_CLOUD_DATABASE/d1cb63c8dd8e4c35a0f18aef632687f0 Developer Guide (MTA, Business App Studio): https://help.sap.com/docs/HANA_CLOUD_DATABASE/c2b99f19e9264c4d9ae9221b22f6f589

Native SAP HANA Cloud development uses the HANA Deployment Infrastructure (HDI): you write design-time source files that HDI deploys transactionally into an isolated HDI container (a schema plus a technical user). Objects are created by name in a container — you never write raw CREATE TABLE DDL against the schema.

Project structure (native db/ module)

db/
├── src/
│   ├── models/
│   │   ├── Books.hdbtable
│   │   ├── BooksByAuthor.hdbcalculationview
│   │   └── getBookStats.hdbprocedure
│   ├── roles/
│   │   ├── app_access.hdbrole
│   │   └── external_access.hdbgrants
│   └── synonyms/
│       └── ExternalOrders.hdbsynonym
├── .hdiconfig          # maps file suffixes → HDI build plugins
└── .hdinamespace       # namespace rules for the src folder

Column table — .hdbtable

HANA is a column store by default; prefer COLUMN TABLE for analytical/transactional app data.

COLUMN TABLE "Books" (
  "ID"        INTEGER NOT NULL,
  "TITLE"     NVARCHAR(200) NOT NULL,
  "AUTHOR_ID" INTEGER,
  "PRICE"     DECIMAL(9,2),
  "CURRENCY"  NVARCHAR(3),
  PRIMARY KEY ("ID")
)

SQLScript procedure — .hdbprocedure

Prefer declarative (set-based) logic over row-by-row loops; the optimizer parallelizes table variables. Always project explicit columns.

PROCEDURE "getBookStats" (
  IN  author_id INTEGER,
  OUT stats TABLE ("TITLE" NVARCHAR(200), "PRICE" DECIMAL(9,2))
)
LANGUAGE SQLSCRIPT
SQL SECURITY INVOKER
AS
BEGIN
  -- Declarative table variable — no imperative cursor loop
  stats = SELECT "TITLE", "PRICE"
          FROM "Books"
          WHERE "AUTHOR_ID" = :author_id
          ORDER BY "PRICE" DESC;
END;

Calculation view — .hdbcalculationview

Calculation views model analytical logic (star joins, aggregation). Use dimension views for master data and cube views (with a measure) for facts. They are built graphically in SAP Business Application Studio; keep joins on indexed key columns and push filters down.

Roles & privileges — .hdbrole + .hdbgrants

Grant access through roles, never to individual users in design time. Use .hdbgrants to grant the container's object owner privileges on external objects.

// app_access.hdbrole
{
  "role": {
    "name": "app_access",
    "object_privileges": [
      { "name": "Books", "type": "TABLE", "privileges": ["SELECT"] }
    ]
  }
}

Cross-container access — .hdbsynonym

Never hardcode another container's schema name. Reference external objects through a synonym, resolved at deploy time.

// ExternalOrders.hdbsynonym
{
  "ExternalOrders": {
    "target": { "object": "Orders", "schema": "SALES_PROD" }
  }
}

Using native artifacts from CAP

CAP compiles CDS to HANA tables and deploys them into the same HDI container. To expose a hand-written native object (view, table, calculation view) to a CAP service, declare a matching CDS entity and point at the object via a .hdbsynonym — CAP reads it like any other entity. See cds-modeling for the CDS side and btp-deployment for the container binding in mta.yaml.

AI / Vector Engine (optional)

For embeddings and similarity search, HANA Cloud provides the native REAL_VECTOR type and COSINE_SIMILARITY / L2DISTANCE functions — the storage layer behind CAP RAG scenarios.

COLUMN TABLE "Embeddings" (
  "ID"     INTEGER PRIMARY KEY,
  "TEXT"   NVARCHAR(5000),
  "VECTOR" REAL_VECTOR(1536)
)

HANA Cloud also provides the native VECTOR_EMBEDDING function, which generates embeddings from text directly in the database (no external embedding service needed for supported models):

-- Compute embedding and find similar rows in one query
SELECT TOP 5
  "ID", "TEXT",
  COSINE_SIMILARITY("VECTOR", VECTOR_EMBEDDING('search query text', 'QUERY', 'SAP_GXY.20250407')) AS score
FROM "Embeddings"
ORDER BY score DESC

Common mistakes to avoid

• ❌ SELECT * in views/procedures — ✅ project only needed columns; the column store rewards narrow projections
• ❌ Writing raw CREATE TABLE against the schema — ✅ deploy .hdbtable via HDI so changes are transactional and versioned
• ❌ Row-by-row cursor loops in SQLScript — ✅ use declarative table variables so the optimizer parallelizes
• ❌ ROW TABLE for large analytical data — ✅ COLUMN TABLE (the HANA default) unless you have a specific high-write, single-row-access case
• ❌ Hardcoding another container's schema — ✅ use a .hdbsynonym
• ❌ Granting privileges directly to users at design time — ✅ bundle them in .hdbrole
• ❌ Dropping a column type/length in .hdbtable on redeploy — ✅ HDI blocks data-losing changes; use .hdbmigrationtable for controlled migrations
• ❌ Editing objects directly in the runtime schema — ✅ all changes go through the HDI design-time source, or the next deploy reverts them