SAP Community - SAP HANA Cloud

Automated SQL Plan Management to recover from degraded performance

2026-06-24T13:33:10.872000+02:00

You apply an upgrade over the weekend. Monday morning, someone reports that a critical reporting query is running much slower. You dig into the plan cache, compare before/after execution plans, find the optimizer chose a different join order, capture the old plan, pin it — and hours later, things are back to normal.

SAP HANA Cloud's SQL Plan Advisor, combined with SQL Plan Stability, now supports a fully automated detect-test-apply cycle that handles this class of degraded performance without manual intervention. Here is how it works and how to configure it.

The Two Pieces You Need to Know

SQL Plan Stability — Your Insurance Policy

SQL Plan Stability lets you capture an Abstract SQL Plan (ASP) for any SELECT statement. An ASP is a compact, engine-independent representation of an execution plan's key structural decisions: join order, join types, access paths, aggregation strategies. It is stored persistently and can be used later to regenerate that same physical plan, even after a software update or statistics refresh that would otherwise cause the optimizer to choose something different.

Key points:
- SAP HANA Cloud now automatically collects ASP for every distinct HEX plans and corresponding statistics.
- For non-HEX, only the statistics are collected for the corresponding statement hash

As ASPs are collected for every compiled plans with its corresponding statistics, we have a clearer understanding of what is a good plan versus a bad plan. This information is used it to protect against future degradation.

SQL Plan Advisor — The Automated Testing Engine

SQL Plan Advisor is the active component. It continuously monitors SQL execution, detects performance degradation by comparing the current execution plans statistics over the statistics stored in SQL Plan Stability, and now automatically runs A/B tests between the current plan and candidate alternatives to find and validate a better one.

The candidate plan types it evaluates are:

Candidate Type	What It Is
NON_HEX	A plan generated by the non-HEX execution engine, tested when the HEX plan degrades
CAPTURED_ABSTRACT_SQL_PLAN	An ASP previously captured via SQL Plan Stability
PLAN_VARIANT	An alternative plan from the plan cache, typically tied to a different parameter binding by caching multiple plans for a given statement hash NOT AUTOMATICALLY TESTED

For parameterised queries, it is first determined if it can be covered by Plan Variant based on selectivity. If covered, the SQL Plan Advisor can test and collect statistics over the current plan and 50 with each alternative and checks for deviance before issuing a recommendation. As the testing maybe extensive, Plan Variant is currently scoped out for the automated testing.

The Fully Automated Flow

When configured for full automation, the pipeline looks like this:

Query executes
│
▼
HANA detects degradation (execution / CPU time compared to history)
│
▼
Statement auto-registered in SQL Plan Advisor
│
▼
Advisor tests current plan vs. candidates (NON_HEX, ASP)
over multiple live executions — no downtime, no test window
│
▼
Winner identified by empirical statistics
│
▼
Better plan auto-applied on the next execution
│
▼
Monitoring views updated — DBA can review at any time

The DBA is not in the critical path. You are informed after the fact, not paged during the incident.

Configuration

Step 1 — Enable SQL Plan Stability Capture for Critical Queries

Do this before your next update. In SAP HANA Cloud Central, navigate to SQL Plan Stability and enable capture for your most sensitive statements. For most instances, this should be already enabled.

Or use SQL directly:

-- Enable capture for a specific statement hash
ALTER SYSTEM ALTER SQL PLAN CACHE ENTRY '<statement_hash>'
SET PLAN STABILITY CAPTURE PLAN = TRUE;

Captured ASPs land in `M_SQL_PLAN_CACHE_EXECUTION_PLAN_STATISTICS` and are referenced in the `CAPTURED_ABSTRACT_SQL_PLAN` column of `M_SQL_PLAN_ADVISOR`.

Step 2 — Configure SQL Plan Advisor Parameters

In SAP HANA Cloud Central, navigate to SQL Plan Advisor and enable Register Queries, and set Test Queries and Apply Advice to Automatically which should be the default configuration

Monitoring

You can monitor all of this graphically in SAP HANA Cloud Central → SQL Plan Advisor, where the UI shows registered queries, test progress, performance comparisons, and applied recommendations in one view.

How SQL Plan Stability and SQL Plan Advisor Work Together

The two features are complementary, not redundant:

- SQL Plan Stability is reactive and defensive: capture a known-good plan, apply it when something goes wrong. It requires you to have captured an ASP beforehand.

- SQL Plan Advisor is proactive and exploratory: it detects degradation automatically, tests multiple candidates (including your captured ASPs), and applies the empirically best one.

The combined strategy:

1. Before a QRC update: Capture ASPs for your critical statements via SQL Plan Stability which should be already captured.
2. After the update: If the optimizer picks a worse plan for any of those statements, SQL Plan Advisor detects the degradation, tests the captured ASP against the new plan, and automatically applies the better one. Or, if a non-HEX plan is now converted to a HEX plan but the performance have degraded then reverts the execution back to non-HEX.
3. Ongoing: Advisor continues monitoring for new degradation across the full workload, not just the statements you pre-selected.

You get both a safety net (captured ASPs) and an autonomous recovery mechanism (Advisor auto-apply).

What Gets Automated vs. What Still Needs DBA Judgement

Fully automated:

- Detection of performance degradation
- Registration of degraded statements as test candidates
- A/B testing based on historical plans statistics.
- Application of the most performant plan

Still requires DBA attention:

- Parameterized queries which can be covered by Plan Variant should be manually tested if Plan Variant is applicable.---

Conclusion

The automated testing was first applied with QRC 01/2026 version and we have been closely monitoring on a daily basis. Based on our telemetry data, 155 plans have been corrected back to a more performant plan based on historically captured ASPs. We have noticed up to 20 times performance increases after the recovery. Most of the reasons of degraded performance was due to statistics changes in the underly tables or plan changes for parameterized queries which couldn't be covered by Plan Variant.

We are planning to improve the coverage of SQL Plan Advisor and improve the usability of our tooling for better manage SQL plans and improve user experiences.

References

- SQL Plan Advisor — SAP Help Portal
- Automating SQL Plan Management with SQL Plan Advisor — SAP Learning
- Leveraging SQL Plan Stability for Performance Optimization — SAP Learning
- Protect from Performance Regression with SQL Plan Stability — SAP Community Blog
- Using SQL Plan Advisor in SAP HANA Cloud Central — SAP Help Portal

Replicating SAP S/4HANA CDS View Entities into SAP HANA Cloud: A Practical Guide

2026-06-24T13:33:30.571000+02:00

In analytics, speed is everything—yet pulling real-time data from a live SAP S/4HANA system remains a bottleneck for many organizations. When your reports rely on remote queries, they are instantly vulnerable to network latency and cross-system traffic. CDS view replication changes the game by moving the data to where the processing happens: caching it directly into SAP HANA Cloud and automating background syncs for instant reporting.

This post walks through everything you need to know to set up, operate, and monitor CDS view replication using the SAP HANA smart data access **abapodbc** adapter which is an extension to the already available federation as introduced by my colleague SeungjoonLee and my previous blog.

Related Blogs:

What Is CDS View Entity Replication?

At its core, CDS view replication lets you maintain a local copy of an SAP S/4HANA CDS view as a native table inside SAP HANA Cloud. Once the initial snapshot is loaded, subsequent updates are applied using **Change Data Capture (CDC)** — only inserts, updates, and deletes are fetched and replayed, not the entire dataset.

The result is a target table in SAP HANA Cloud that stays in sync with your S/4HANA source, with a freshness you control.

Why This Matters

- Performance: Local queries beat remote queries — no cross-system round trips at runtime.
- Availability: Your replica stays accessible even if the S/4HANA system is under maintenance.
- Flexibility: You can project specific columns or filter rows at the subscription level, so you only replicate what you need.
- Integration: The replicated table is a plain SAP HANA table — you can join it with other local data, build calculation views on top of it, or expose it via BTP services.

The Two Replication Phases

Replication is split into two distinct phases:

Phase 1: Initial Load

The initial load takes a full snapshot of the CDS view and copies it into the target table. You trigger this with the `QUEUE` command. The system handles chunking and parallelism internally — you just monitor progress.

One important caveat: the initial load does **not** check whether the target table is empty. If you're reloading after a reset, truncate the target table first.

Phase 2: Delta Load

Once the initial load completes, only changes (inserts, updates, deletes) are replicated. You have two options here:

- System-scheduled replication (`DISTRIBUTE`): The system automatically runs delta replication at a configurable interval. Set it once, let it run.
- User-driven replication (`DELTA LOAD`): You explicitly trigger replication whenever you want. Useful for controlled refresh scenarios or testing.

Setting It Up:

Pre-requisite A — Setup Source System

Pre-requisite B — Configure Cloud Connector to Source

Configure Cloud Connector
Configure Access Control (RFC) in the SAP BTP Connectivity documentation

Step 1 — Create a Remote Source

You need an abapodbc adapter remote source that connects SAP HANA Cloud to your S/4HANA system. This is your network tunnel between the two systems.

Step 2 — Create the Virtual Table and Target Table

Create a virtual table from the remote source (this is your read-through proxy to the CDS view), and create a local target table that will hold the replicated data.

Step 3 — Create the Remote Subscription

This is where the replication is defined. The `CREATE REMOTE SUBSCRIPTION` statement ties everything together:

-- Simplest form: replicate everything
CREATE REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION"
ON "SOURCE_CDS_VIEW"
TARGET TABLE "TARGET_TABLE";

-- Column projection: only replicate specific fields
CREATE REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION"
AS (SELECT "COL1", "COL2", "COL3" FROM "SOURCE_CDS_VIEW")
TARGET TABLE "TARGET_TABLE";

-- Row filter: only replicate rows matching a condition
CREATE REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION"
AS (SELECT * FROM "SOURCE_CDS_VIEW" WHERE "DEPARTMENT" = 'SALES')
TARGET TABLE "TARGET_TABLE";

The `WHERE` clause supports `=`, `<>`, `<`, `<=`, `>`, `>=`, `BETWEEN`, `IN`, `LIKE`, and logical operators `AND`/`OR`/`NOT`. A few syntax rules apply: field names must be double-quoted, string values single-quoted, and the right-hand side of a comparison must be a literal (no field-to-field comparisons).

Step 4 — Perform the Initial Load

ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" QUEUE;

Monitor progress in the `M_REMOTE_SUBSCRIPTION_INITIAL_LOADS` system view. The number of chunks can increase dynamically during the load as the system generates new ones.

Step 5 — Enable Delta Replication

Choose your mode:

-- Scheduled: run every 15 minutes
ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" DISTRIBUTE INTERVAL 900;

-- On-demand: trigger manually
ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" DELTA LOAD;

Load Behaviors: Normal vs. Upsert

When you create the subscription, you choose how DML operations are applied to the target table.

Behavior	INSERT	UPDATE	DELETE
Normal	Applied directly	Applied directly	Applied directly
Upsert	Applied as UPSERT	Applied as UPSERT	Converted to UPDATE with `CHANGE_TYPE = 'D'`

The upsert mode is useful when you want to preserve a history of deletions or need idempotent replay. It requires three additional metadata columns in the target table as shown below:

CREATE TABLE "TARGET_TABLE" (
"ID" INT,
"NAME" NVARCHAR(100),
"CHANGE_TYPE" NVARCHAR(1), -- 'A' = insert/update, 'D' = delete
"CHANGE_TIME" TIMESTAMP,
"CHANGE_SEQ" BIGINT -- optional: portion identifier
);

CREATE REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION"
ON "SOURCE_CDS_VIEW"
TARGET TABLE "TARGET_TABLE"
CHANGE TYPE COLUMN "CHANGE_TYPE"
CHANGE TIME COLUMN "CHANGE_TIME"
CHANGE SEQUENCE COLUMN "CHANGE_SEQ"
UPSERT;

Managing Replication Day-to-Day

Adjusting the Schedule

You can update the replication interval without triggering an immediate run — useful for shifting frequency during off-peak hours:

ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" INTERVAL 1800; -- 30 minutes

To immediately trigger replication AND update the interval:

ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" DISTRIBUTE INTERVAL 1800;

Suspending During Maintenance

If your S/4HANA system is going down for maintenance, suspend replication at the remote source level. All subscriptions under that source are paused; running jobs are allowed to finish but no new ones are scheduled.

ALTER REMOTE SOURCE <remote_source_name> SUSPEND CAPTURE;

-- When the system is back up:
ALTER REMOTE SOURCE <remote_source_name> RESUME CAPTURE;

Note that `SUSPEND CAPTURE` only affects system-scheduled jobs. Manual `DELTA LOAD` commands still work.

Cancelling a Running Job

If a replication job is consuming too many resources or is stuck, you can cancel it mid-execution:

-- Find the running job
SELECT CONNECTION_ID
FROM M_REMOTE_REPLICATION_JOBS
WHERE STATUS = 'RUNNING'
AND REMOTE_SUBSCRIPTION_NAME = 'ABAP_SUBSCRIPTION';

-- Cancel it
ALTER SYSTEM CANCEL SESSION '<connection_id>';

The system rolls back any partial changes, restoring the target table to its pre-job state. The job is automatically rescheduled for its next interval.

Resetting vs. Dropping

Reset returns the subscription to its initial state without removing it. Use this when you need to re-run the full initial load:

ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" RESET;
TRUNCATE TABLE "TARGET_TABLE";
ALTER REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION" QUEUE;

Drop permanently removes the subscription and cleans up resources on the ABAP source. The target table is retained.

DROP REMOTE SUBSCRIPTION "ABAP_SUBSCRIPTION";

Monitoring: The System Views You Need

SAP HANA provides a set of dedicated system views for CDS view replication. Here's when to use each one:

View	Use Case
REMOTE_SUBSCRIPTIONS	Check subscription configuration, status, and the current replicated version (`EXTERNAL_VERSION_ID`)
M_REMOTE_SUBSCRIPTIONS	Runtime health and status of active subscriptions
M_REMOTE_REPLICATION_JOBS	Full lifecycle of scheduled jobs — PLANNED, RUNNING, COMPLETED, FAILED, CANCELLED
M_REMOTE_SUBSCRIPTION_INITIAL_LOADS	Initial load progress by chunk: status, record count, execution time
M_REMOTE_SUBSCRIPTIONS_ABAPODBC	ABAP-side replication ID and last processed portion ID

A few useful queries to keep handy:

-- Is my initial load done?
SELECT CHUNK_ID, TOTAL_RECORD_COUNT, EXECUTION_STATUS, EXECUTION_TIME
FROM M_REMOTE_SUBSCRIPTION_INITIAL_LOADS
WHERE REMOTE_SUBSCRIPTION_NAME = 'ABAP_SUBSCRIPTION';

-- What's my latest replicated version?
SELECT EXTERNAL_VERSION_ID
FROM REMOTE_SUBSCRIPTIONS
WHERE SUBSCRIPTION_NAME = 'ABAP_SUBSCRIPTION';

-- Did any scheduled jobs fail recently?
SELECT STATUS, ERROR_NUMBER, ERROR_MESSAGE, START_TIME, END_TIME
FROM M_REMOTE_REPLICATION_JOBS
WHERE REMOTE_SUBSCRIPTION_NAME = 'ABAP_SUBSCRIPTION'
ORDER BY START_TIME DESC;

Workload Management

Automatic replication jobs participate in SAP HANA's native admission control. You can define workload class thresholds to prevent replication from overwhelming the system:

CREATE WORKLOAD CLASS "AbapReplicationControl"
SET 'ADMISSION CONTROL REJECT CPU THRESHOLD' = '90',
'ADMISSION CONTROL QUEUE CPU THRESHOLD' = '70';

CREATE WORKLOAD MAPPING "AbapReplicationMapping"
WORKLOAD CLASS "AbapReplicationControl"
SET 'APPLICATION NAME' = '_SYS_REMOTE_REPLICATION_ABAP_DELTA_LOAD';

Jobs that exceed the QUEUE threshold are delayed; jobs that exceed the REJECT threshold fail with an error and are rescheduled.

Limitations to Know Before You Start

Before you commit to a schema design, check these constraints:

- Load behavior: Only Normal and Upsert are supported. INSERT and ARCHIVE load behaviors are not. (Archived data in the source are converted to deletes and will be removed from the target table)
- Schema changes: The `WITH SCHEMA CHANGES` clause is not supported. If the CDS view schema changes, replication will fail and you'll need to manually update the target table and recreate the subscription.
- Initial load: Only the automated `QUEUE` command is supported. The manual `INITIAL LOAD PREPARE/EXECUTE/FINALIZE` flow is not available.
- Subquery expressions: Column projection and row filtering work. Function calls like `UPPER()` or arithmetic expressions in the subquery do not.
- Subscription query: Once created, the subscription query cannot be changed. `ALTER REMOTE SUBSCRIPTION … REFRESH DEFINITION` is not supported. Recreate it if you need to change the filter or projection.
- Target type: Only `TARGET TABLE` is supported. `TARGET PROCEDURE` and `TARGET TASK` are not.
- **NULL handling**: Empty values on the ABAP side (empty strings, zeros) may arrive as `NULL` in the target table. Account for this in downstream logic.

---

Summary

CDS view replication with the abapodbc adapter gives you a clean, CDC-based pipeline from SAP S/4HANA into SAP HANA Cloud. The lifecycle is straightforward: create the subscription, run the initial load with `QUEUE`, then choose between scheduled replication (`DISTRIBUTE`) or on-demand updates (`DELTA LOAD`). Built-in system views give you full visibility into job status, and native workload management ensures replication doesn't compete with your critical workloads.

The main things to keep in mind:

1. Truncate the target table before re-running the initial load — the system won't do it for you.
2. Schema changes on the source CDS view require a manual rebuild of the subscription.
3. Orphaned replications can silently drain ABAP resources — check with `DHADM` after any failed `CREATE REMOTE SUBSCRIPTION`.
4. Failed scheduled jobs are **not** automatically rescheduled — you need to re-issue `DISTRIBUTE` after resolving the error.

With that, you have everything you need to get replication running and keep it healthy in production.

Banking Sentinel: A Multi-Agent Credit-Risk Copilot on SAP BTP, Built on a Mixed AI Stack

2026-06-24T15:03:44.334000+02:00

1. The Problem We Are Solving

Every bank faces the same invisible risk: a customer looks safe in isolation but is quietly part of a web of connected entities (family trusts, guarantor networks, subsidiary companies) whose combined exposure is far beyond what any single credit file shows.

A borrower with a modest loan today can be the linchpin of a group with ten times the exposure. By the time a human analyst pieces it together, it may be too late.

The traditional tools are spreadsheets, batch reports, and credit scorecards that look at one dimension at a time. A scorecard says the debt-to-income ratio is 7.20 times, already a concern, already on file as a breach. Fine. But it does not tell you:

That the same customer’s income contract expires in 82 days
That when it does, their effective DTI rockets to 32.05 times, over 4x the regulator’s limit
That their loan is under-collateralized by AUD 620,000
That the connected-party graph has no relationship edge for this customer at all. A guarantor obligation only surfaces through a separate table, easy to miss if you only check the graph
That a shared guarantor connects this customer to a family trust, and that correctly scoping group exposure to only the loans within that group (not a guarantor’s unrelated obligations elsewhere in the portfolio) is its own real engineering problem, not just a data-fetching one

No single analyst. No single report. No single tool catches all of this at once.

Banking Sentinel does.

▶️Watch the demo on YouTube

GitHub: https://github.com/shahidla/Banking-Sentinel

2. Why This Matters

A borrower’s risk doesn’t live in one place. It’s spread across payment behaviour, where their finances are heading, who they’re financially connected to, and whether there’s enough evidence to act on any of it. Miss one of those and a loss event can slip through a credit file that otherwise looks fine. Banking Sentinel checks all four, each step building on what the last one found, and turns the result into a single risk brief a human can review in under two minutes.

On the SAP side: this is a mixed-stack system with a deliberate boundary, not a claim that everything is SAP-native. The data and ML layer is SAP and proven (HANA Cloud, CAP, RPT-1, interchangeable with HANA PAL and Knowledge Graph Engine in production, see §11). The reasoning layer (the LLM, LangGraph, Langfuse) is not SAP, because AI Core isn’t available on the BTP trial tier this runs on. That’s an access constraint, not a verdict on SAP’s capability.

On the AI side: four patterns do real work here, not added for show. A ReAct loop drives graph traversal. A Reflexion-style critic (Reflection) checks evidence quality before anything is finalized. Human-in-the-Loop interrupts enforce compliance sign-off. A RAGAS-inspired claim-source check (cosine similarity, not the RAGAS library) catches an LLM asserting something the evidence doesn’t support, exactly what happens in §6 and §7.

3. What Banking Sentinel Does

Banking Sentinel is a multi-agent AI risk intelligence system deployed on SAP BTP (Business Technology Platform). A risk analyst types a single sentence: “Analyse credit risk for customer 30100003.” Within roughly 75 to 110 seconds (HITL off or on), seven AI agents have examined the customer across four independent risk dimensions and produced an APRA-compliant risk brief, complete with regulatory references, confidence scores, and a clear recommendation.

The system produces: - A risk score (0-100) with level: LOW / MEDIUM / HIGH / CRITICAL - Five specific findings with regulatory standard, severity, evidence source, and confidence score - Three actionable recommendations - Identified data gaps and uncertainties, not hidden, explicitly surfaced - A regulatory audit trail under APRA CPS 230 and APS 221 - A flag: APRA-Ready (true/false), whether the evidence is strong enough to take to a board

The system refuses to: - Approve or reject a loan (it is a co-pilot, not a decision-maker) - Delete records - Override risk flags - Operate without a human sign-off when the risk is material

4. The Technology Stack

Component Technology Purpose

Runtime Platform	SAP BTP Cloud Foundry	Deployment, scaling, service bindings
Application Framework	SAP CAP (CDS + Node.js)	OData APIs, HANA binding, CDS models
Primary Database	SAP HANA Cloud	All SAP TRBK/BCA banking tables
Vector Store	SAP HANA Cloud Vector Engine	APRA regulatory document embeddings
Graph Engine	GraphDB (RDF/SPARQL), HANA KGE in production	Connected-party traversal
Tabular AI Model	SAP RPT-1 (rpt.cloud.sap)	Tabular risk scoring without AI Core
Anomaly Detection	scikit-learn Isolation Forest (HANA PAL in production)	Statistical payment anomaly detection
LLM	Claude Haiku 4.5 (Anthropic)	All natural language reasoning
Agent Orchestration	LangGraph (StateGraph)	Multi-agent pipeline with conditional routing
State Persistence	PostgreSQL / Supabase	LangGraph checkpoint, survives CF restarts
Embeddings	OpenAI text-embedding-3-small	APRA document vectorisation
Observability	Langfuse	Per-agent token usage, latency, traces
Real-time UI	Server-Sent Events (SSE)	Live agent progress in browser
Event Mesh	Solace (Advanced Event Mesh)	Publishes pipeline events to `banking/*` topics. A real, persistent broker connection, genuinely sending messages, but no consumer is wired up within this demo; the UI’s live updates come via SSE, not Solace
Frontend	Vanilla HTML/CSS/JS	Bank-grade UI, no framework dependencies

Why SAP RPT-1

RPT-1 is SAP’s tabular foundation model, available via a public consumer API at rpt.cloud.sap without requiring AI Core or SAP AI Launchpad. It uses in-context learning: send it example rows from your portfolio with known risk categories, then ask it to classify your target customer. No training. No fine-tuning. Immediate results. Banking Sentinel uses it as the foundational risk score before any LLM reasoning begins.

Why LangGraph

LangGraph is a graph-based agent orchestration framework. Each agent is a node. Data flows between nodes via a typed state object. Conditional edges allow the pipeline to branch: a low-risk customer skips the graph traversal and jumps straight to synthesis, while a high-risk customer goes through all four specialist agents. A re-query loop allows the Reflection agent to send the Relationship Agent back for a deeper traversal if the first pass was incomplete. This is impossible to express cleanly in a simple chain. It needs a state machine.

Why HANA Vector Engine

APRA regulatory documents (APS 221, CPS 230, DTI Notices) are embedded into HANA Cloud’s native vector engine. When the Synthesis Agent writes the risk brief, it retrieves the most relevant regulatory clauses by semantic similarity, not keyword matching. This means the risk brief cites the actual paragraph of the actual regulation that applies to the specific risk being assessed.

5. The Architecture

User query → [Intake Agent]
│
┌─────────┼─────────┐
▼ ▼ ▼
Simple Query Risk Rejection
(direct Analysis (refuses
DB lookup) pipeline) approvals)
│
[Pattern Agent]
RPT-1 + PAL + LLM
│
Score < 30 ──→ [Synthesis]
Score ≥ 30 ──→ [Trajectory Agent]
│
[Relationship Agent]
ReAct loop: traverse graph,
calculate exposure, check APRA
│
[Reflection Check]
LLM evaluates evidence quality
│
Confidence < 0.70 ──→ [Relationship] (re-query, max 2x)
Confidence ≥ 0.70 OR max re-queries reached ──→ [Human Approval]
│
← interrupt ←
Risk officer reviews
and approves
│
[Synthesis Agent]
HANA Vector + APRA brief
│
[END]
Report persisted
to HANA + AuditLog

State flows through the pipeline in one typed object. Every agent reads everything every previous agent produced. The Synthesis Agent sees Pattern’s anomalies, Trajectory’s DTI projections, Relationship’s graph findings, and Reflection’s quality gaps, all at once. Nothing is lost between agents.

6. The Seven Agents: A Full Walkthrough

Agent 0: Intake Agent

Purpose: Parse the user’s query. Decide what kind of request this is. Route accordingly.

The problem it solves: A risk officer might type “Analyse 30100001” or “What is the DTI for 30100001” or “Approve the loan for 30100001.” These are three completely different requests. The first triggers a full seven-agent pipeline. The second is a simple database lookup. The third must be refused. Banking Sentinel is a co-pilot, not a decision-maker.

How it works: Claude Haiku reads the user’s query against a system prompt that defines three intent categories: - RISK_ANALYSIS: triggers the full agent pipeline - SIMPLE_DATA_QUERY: answered directly from HANA, no pipeline - INAPPROPRIATE_REQUEST: any attempt to approve, reject, delete, modify, or override

The agent also extracts the customer ID. SAP Business Partner numbers are 8-digit codes (e.g. 30100001). The agent is instructed to extract them exactly, no reformatting.

Output (stored in pipeline state):

{
 "isRiskAnalysis": true,
 "isSimpleDataQuery": false,
 "isInappropriateRequest": false,
 "customerId": "30100001",
 "description": "Analyse credit risk for customer 30100001"
}

What happens next: If isRiskAnalysis, the pipeline continues to the Pattern Agent. If isSimpleDataQuery, the query is delegated to a published MCP server (cds-db-nlquery-mcp) that translates it into a real CDS query, including JOINs and aggregates where needed, directly against db/schema.cds. A second Claude Haiku call then turns the result into a concise written answer. If isInappropriateRequest, a firm refusal is returned explaining that the system does not approve or override. That is a human decision.

A live SIMPLE_DATA_QUERY example:

Query: "What is the total loan amount across all customers"

This isn’t a single-row lookup. It requires a real SQL aggregate (SUM(AMOUNT)) across every loan in the portfolio, with no customer ID given at all. The Intake Agent correctly classifies it as SIMPLE_DATA_QUERY with customerId: null. The MCP server plans a structured query descriptor ({"entity": "Loans", "aggregate": [{"fn": "sum", "col": "AMOUNT", "as": "total_loan_amount"}]}), never raw SQL text, executes it as a real CDS query, and returns the result for Claude Haiku to phrase:

Total Loan Amount Across All Customers Total Loan Amount: AUD 31,773,000.00
Would you like a full risk analysis of any specific borrower

Verified against live HANA: 30 loan records, AUD 31,773,000.00, confirmed against a direct SUM(AMOUNT) query as ground truth. This needed two rounds of fixes in the underlying cds-db-nlquery-mcp package: the query-planning LLM occasionally emitted a function-call string ("SUM(AMOUNT)", then a wider variant with a trailing alias) as a literal column name instead of using the structured aggregate field. Both are now rejected up front with an actionable error instead of reaching HANA as a cryptic failure or, worse, silently returning a wrong total.

Agent 1: Pattern Agent

Purpose: Establish the baseline risk signal. “Something feels wrong,” before any specific rule fires.

The problem it solves: A credit scorecard tells you a number. But a number alone does not tell you whether the payment behaviour is suspicious, whether the debt structure is unusual, or whether there are statistical outliers in how this customer compares to the portfolio. Pattern Agent runs three methods and combines their signals.

How it works: RPT-1 (Method 1) runs alone first. We diagnosed empirically that it was prone to BTP-only timeouts when racing the other two methods inside the same single-threaded event loop. Isolation Forest (Method 2) and the LLM narrative pass (Method 3) then run in parallel with each other, but not with RPT-1.

Method 1: SAP RPT-1 (Tabular Foundation Model) The agent fetches up to 50 historical loan cases from BCA_CREDIT_HISTORY, a dedicated table of independently-labelled outcomes, to use as in-context examples. Each row has: case ID, DTI ratio, breach flag, total debt, annual income, and a known arrears_outcome (LOW/MEDIUM/HIGH/CRITICAL). It sends these to rpt.cloud.sap/api/predict alongside the target customer’s current profile (from BCA_DTI) with arrears_outcome marked [PREDICT]. RPT-1 applies in-context learning and returns a predicted arrears-risk category with a confidence score, mapped to a 0-100 scale via fixed floors (LOW:0, MEDIUM:26, HIGH:51, CRITICAL:76).

For 30100003 (live run, 2026-06-24): RPT-1 returns CRITICAL with confidence 0.46.

Method 2: Isolation Forest Anomaly Detection (scikit-learn / HANA PAL) The agent trains an Isolation Forest model on a 2D feature vector, payment delay days and dunning level (0-3), drawn from up to 500 rows combined from DFKKOP (open items) and DFKKOPK (cleared items), the bank’s full payment-history tables. Isolation Forest detects outliers by measuring how easily a data point can be isolated from the rest: anomalies are isolated in fewer splits. The 2D feature captures joint escalation: a customer whose delay and dunning level are both drifting gets flagged even when neither alone crosses a fixed threshold. Each of the customer’s payment rows is then scored: label -1 for outlier, 1 for inlier.

For 30100003: 0 of 7 payment rows flagged as outliers. This customer’s single loan has no statistically unusual payment behaviour on its own. (The risk signal here comes from RPT-1 and the LLM method below, not from this statistical check, a good illustration of why Pattern Agent runs three independent methods rather than relying on one.)

Method 3: LLM Narrative Anomaly Detection (Claude Haiku) The raw customer data (loans, DTI record, up to 12 months of cleared payment history per loan, and collateral) is sent to Claude Haiku. The LLM is told the current APRA DTI threshold (fetched from RegulatoryThresholds, not hardcoded) and asked to find two specific things a single-row statistical check can’t: an escalating trend across a loan’s payment history (delay and/or dunning level rising over recent months, described narratively, e.g. “Loan L-001 deteriorated from on-time to 81-day delay / dunning level 3 over the last 5 months”), and under-collateralization (a loan’s amount exceeding the total value of its pledged collateral). It’s explicitly told not to flag a single row’s overdue days in isolation. That’s Method 2’s job.

For 30100003: 2 anomalies identified, including loan L-004 (AUD 2.1M) exceeding its pledged collateral (AUD 1.48M) by AUD 620,000, a security deficiency.

Tables read from HANA: - bankingsentinel.BCA_CREDIT_HISTORY: 50 labelled historical cases for RPT-1 in-context learning - bankingsentinel.BCA_DTI: this customer’s current DTI ratio, annual income, total debt, breach flag, income expiry. The row RPT-1 predicts against - bankingsentinel.Loans: loan IDs, amounts, types - bankingsentinel.DFKKOP / bankingsentinel.DFKKOPK: open and cleared payment transactions (delay days, dunning level) - bankingsentinel.BCA_COLLATERAL: collateral against loans - bankingsentinel.RegulatoryThresholds: current APRA DTI threshold

Output (for 30100003):

{
 "riskScore": 87,
 "riskLevel": "CRITICAL",
 "confidence": 0.46,
 "signal": "unclear",
 "anomalies": [
 "Loan L-004 (AUD 2.1M) exceeds collateral (AUD 1.48M) by AUD 620,000",
 "..."
 ]
}

What happens next: If riskScore is below 30, the pipeline skips directly to Synthesis. No graph traversal needed. For 30100003 with score 87, the pipeline continues to the Trajectory Agent.

Agent 2: Trajectory Agent

Purpose: Project the customer’s financial position forward in time. “Where is this heading”

The problem it solves: Current DTI is 7.20 times. The customer’s income is from a contract that expires in 82 days. When that contract ends, the customer has the same debt but a fraction of their current income remaining this year. What does DTI look like then And separately, even without the income expiry, what does a standard interest-rate-rise stress test do to this customer’s serviceability

How it works:

Step 1: Fetch current DTI data from HANA

SELECT DTI_RATIO, TOTAL_DEBT, ANNUAL_INCOME, INCOME_EXPIRY, BREACH_FLAG
FROM bankingsentinel.BCA_DTI
WHERE PARTNER = '30100003'

Result: DTI_RATIO=7.20, TOTAL_DEBT=2,100,000, ANNUAL_INCOME=291,667, INCOME_EXPIRY=‘2026-09-15’, BREACH_FLAG=true

Step 2: Fetch the APRA DTI threshold dynamically

SELECT LIMIT_PCT FROM bankingsentinel.RegulatoryThresholds
WHERE THRESHOLD_TYPE = 'DEBT_TO_INCOME'

This is the key: the threshold is not hardcoded. It reads from the database, which can be updated in real time. For example, when the APRA Notice button is clicked in the UI, the threshold changes from 8.0 to 6.0 and the next run of the pipeline reflects the new regulatory position immediately.

Step 3: Calculate Forward DTI (income-expiry projection)

The formula: when income expires in N days, only N/365 of annual income remains effective this year.

Formula:
effectiveIncome = annualIncome × (daysToExpiry / 365)
futureDti = totalDebt / effectiveIncome

For 30100003:
daysToExpiry = 83
effectiveIncome = annualIncome × (83 / 365) ← only 23% of income remains
futureDti = totalDebt / effectiveIncome = 32.05x

Result: Forward DTI 32.05x, 301% above the APRA 8.0x limit.

Step 4: Calculate a second, independent projection, the rate-stress test

trajectory-agent.js runs a second forward calculation that has nothing to do with income expiry: APRA’s APG 223 serviceability buffer (a standard +3%, read dynamically from RegulatoryThresholds.RATE_STRESS_BUFFER) models what happens if the cost of servicing this debt rises uniformly. The debt side grows, income stays constant.

Formula:
stressedDebt = totalDebt × (1 + RATE_STRESS_BUFFER_PCT / 100)
futureDtiRateStress = stressedDebt / annualIncome

For 30100003:
stressedDebt = 2,100,000 × 1.03 = 2,163,000
futureDtiRateStress = 2,163,000 / 291,667 = 7.42x

This runs independently of Step 3. A customer could pass the income-expiry check but fail the rate-stress check, or vice versa. For 30100003 the income-expiry trajectory is already the dominant signal, but the rate-stress number (7.42x) is calculated and carried in the state regardless.

Step 5: Check for conflicting signals

The agent compares Pattern Agent findings against the DTI data to identify contradictions. For 30100003, four signals fired: 1. Income contract expires in 82 days. Primary servicing income at risk. 2. Active APRA DTI breach combined with imminent income loss. Compounding risk event. 3. Forward DTI of 32.0× projected. 301% above APRA limit post-expiry. 4. AUD 125,400 in scheduled loan payments fall within the income expiry window.

Tables read from HANA: - bankingsentinel.BCA_DTI: DTI ratio, income, debt, expiry - bankingsentinel.RegulatoryThresholds: current APRA DTI threshold and the APG 223 rate-stress buffer - bankingsentinel.Loans: loan IDs for payment schedule lookup - bankingsentinel.LoanSchedule: scheduled payment amounts and due dates

Output (for 30100003):

{
 "currentDti": 7.2,
 "futureDti": 32.05,
 "futureDtiRateStress": 7.42,
 "daysToExpiry": 83,
 "forwardPosition": "DETERIORATING",
 "conflictingSignals": [
 "Income contract expires in 82 days — primary servicing income at risk",
 "Active APRA DTI breach combined with imminent income loss — compounding risk event",
 "Forward DTI of 32.0× projected — 301% above APRA limit post-expiry",
 "AUD 125,400 in scheduled payments fall within income expiry window"
 ]
}

What happens next: Relationship Agent runs, receiving Pattern’s anomalies and Trajectory’s DTI context in its state.

Agent 3: Relationship Agent

Purpose: Find every entity connected to this customer. Calculate their combined group exposure against APRA’s large exposure limit (APS 221).

The problem it solves: Borrowers often operate within networks: family trusts, corporate groups, guarantor chains. APRA’s APS 221 standard requires banks to aggregate exposure across connected parties. A customer with a AUD 500,000 loan who is a member of a trust with AUD 2.5 million in loans is part of a AUD 3 million exposure group. The bank must know this.

How it works, a ReAct (Reasoning + Acting) Loop:

The agent uses Claude Haiku with three tools it can call iteratively:

Tool 1: hana_graph_traverse Traverses the graph database starting from the customer’s business partner ID. Returns all connected nodes (entities) and edges (relationship types) up to 8 hops deep. The underlying technology is GraphDB (an RDF triple store using SPARQL 1.1) in the demo environment, with HANA Knowledge Graph Engine as the production replacement. The same SPARQL queries work on both.

The data comes from BUT050, SAP’s Business Partner Relationship table, which stores every relationship between business partners: parent-subsidiary, guarantor, family trust member, director, and so on.

Tool 2: exposure_calculator Takes a list of all connected entity IDs and queries BCA_GUARANTOR and Loans to calculate total guaranteed and direct loan exposure across the group.

Tool 3: apra_threshold_check Checks the calculated exposure against APRA’s APS 221 large exposure limit (AUD 7.5 million for this demo). Returns the utilisation percentage.

The ReAct loop in action, first pass:

Step 1: LLM reasons → "I need to find connected parties for 30100003"
LLM acts → calls hana_graph_traverse(startNode: "30100003", depth: 6)
Tool returns → 1 enriched node, 0 chain edges
(no BUT050 relationship row exists for this customer —
the graph itself has no edge here)

Step 2: LLM reasons → "Graph traversal found no connected entities. Check
guarantor data directly."
LLM acts → calls exposure_calculator(entityIds: ["30100003"])
Tool returns → groupExposure: 2,100,000 AUD (the guarantor cover on
loan L-004, from BCA_GUARANTOR — found via the
guarantor table, not via a graph edge)

Step 3: LLM reasons → "Now check against APRA APS 221 threshold."
LLM acts → calls apra_threshold_check(metricType: "aps221", value: 2100000, entityId: "30100003")
Tool returns → aps221Pct: 28.0%, within_limit: true

Step 4: LLM reasons → "Complete. I have enough to summarise."
LLM stops calling tools and returns the finding.

First-pass output:

{
 "nodes": ["30100003"],
 "groupExposure": 2100000,
 "aps221Pct": 28.0,
 "confidence": 0.95,
 "finding": "Customer 30100003 and guarantor 30910005 (Rose Courtney) have combined APS 221 exposure of AUD 2.1M (28% of limit), with no regulatory breach."
}

This first pass is real and grounded. It matches BCA_GUARANTOR exactly (Rose Courtney’s cover on L-004 is AUD 2.1M, the same as the loan amount). Notice what it missed: because BUT050 has no relationship row for this customer, hana_graph_traverse alone returns zero edges. The only reason the guarantor showed up at all is that exposure_calculator separately queries BCA_GUARANTOR directly, a real gap between “what the graph shows” and “what the relational tables show.”

A real bug we found and fixed while building this exact example. exposure_calculator originally summed a connected guarantor’s entire guarantee book, every loan they back anywhere in the portfolio, not just the loans within this customer’s group. Rose Courtney also guarantees loans for three other, unrelated customers elsewhere in the bank. Pulling those in inflated reported group exposure from a correct AUD 2.1M to a false AUD 11.78M (157% of the APS 221 limit) on a re-query, and it happened with two different starting customers who happen to share a guarantor, which is exactly the kind of bug that looks like a one-off coincidence until you check the data twice. The fix scopes guarantee cover to only loans already held by an entity in the connected group. The walkthrough below reflects the corrected behaviour, verified against live HANA after the fix.

What the BUT050 table looks like (for a customer that does have graph relationships, e.g. 30100001):

FROM_PARTNER TO_PARTNER RELTYP

30100001	30910005	CONTACT_PERSON
30100001	30910006	CONTACT_PERSON
30910005	30910006	FAMILY_TRUST_MEMBER

Tables / databases accessed: - GraphDB / HANA KGE: SPARQL traversal of BUT050 relationship graph - bankingsentinel.BCA_GUARANTOR: guaranteed loan amounts - bankingsentinel.Loans: direct loan exposures - bankingsentinel.BCA_SECTOR: sector concentration check

What happens next: Reflection Check evaluates whether this evidence is complete enough to proceed, and for 30100003, it doesn’t think it is.

Agent 4: Reflection Check

Purpose: The pipeline’s quality control layer. Evaluate its own work. Ask: “Do I have enough evidence to stand behind these findings”

The problem it solves: The Relationship Agent found 1 node and 0 edges. But is that complete, or did the traversal stop because there was genuinely nothing more to find Is the CRITICAL Pattern Agent score consistent with a “clean” 28% exposure reading Are the anomalies actually linked to specific exposure items, or floating assertions without an evidence trail

A risk brief built on incomplete evidence is worse than no risk brief, because it creates false confidence.

How it works:

Reflection, a Reflexion-style critic step, means the LLM evaluates the prior agents’ outputs for quality rather than generating new findings. Claude Haiku is given a summary of all four agent findings and asked to assess four dimensions:

Graph Completeness: Did the traversal stop early, or is there genuinely nothing more connected
Signal Consistency: Do Pattern and Relationship findings agree CRITICAL risk score plus clean 28% exposure is an inconsistency worth questioning.
Conflicting Signals: Are the trajectory conflicts explained by the graph, or still unresolved
Evidence Trail: Is every risk claim backed by a specific TRBK record or exposure figure

The LLM returns a confidence score (0.0-1.0) and, if confidence is below 0.70, a specific reQueryHint, a targeted instruction for the Relationship Agent to go deeper.

For 30100003, attempt 1 (live run, post-fix):

{
 "overallConfidence": 0.58,
 "gaps": [
 "Graph traversal incomplete — only 1 node despite CRITICAL risk and a guarantor relationship claimed; guarantor 30910005 not traversed for counter-guarantees, parent entities, or cross-collateral exposure",
 "Pattern confidence (0.46) contradicts Relationship confidence (0.95) — unclear signal plus low pattern confidence suggests risk drivers not yet identified in the graph structure",
 "APS 221 exposure (28%) appears manageable, but CRITICAL risk score (87) and deteriorating DTI (7.2 → 32.05) lack corresponding graph-based evidence; missing connection between income expiry and liability cascade",
 "No TRBK defaults, arrears, or covenant breaches documented despite CRITICAL classification and imminent income loss",
 "Scheduled payment window (AUD 125,400 in 82 days) not mapped to specific loan tranches, guarantees, or maturity dates in the relationship graph"
 ],
 "reQueryHint": "From customer 30100003, traverse all loan tranches and follow guarantor 30910005 for parent guarantees, cross-default clauses, and counter-guarantee relationships. Flag any loans with maturity at or under 82 days.",
 "reasoning": "High trajectory risk is plausible but unmoored from relationship evidence; the single-node graph and low pattern confidence suggest the risk story exists operationally but hasn't been validated through full entity traversal."
}

Routing: 0.58 is below the 0.70 threshold, so it re-queries (attempt 1). Relationship Agent re-runs with the hint.

Relationship Agent, re-query pass: This is where the bug above used to inflate the number. After the fix, the re-traversal genuinely adds one real fact, Rose Courtney’s family-trust connection to 30910006, without changing the exposure figure at all:

{
 "nodes": ["30100003"],
 "groupExposure": 2100000,
 "aps221Pct": 28.0,
 "confidence": 0.72,
 "finding": "Guarantor 30910005 (Rose Courtney) connected to family trust member 30910006; group exposure AUD 2.1M (28% of APS 221 limit) remains non-breaching. Loan tranche expiry, payment schedule, and cross-default clause details were not returned by traversal."
}

Same AUD 2.1M. Same 28%. The only thing that changed is an honest new fact (the family-trust link) and an honest new gap (loan-level facility details aren’t in the graph at all). No fabricated crisis, because there’s no longer a code path that can produce one.

For 30100003, attempt 2 (after the re-query):

{
 "overallConfidence": 0.58,
 "gaps": [
 "Graph traversal halted at 1 node despite CRITICAL risk — no parent entities, upstream guarantors, or trust beneficiaries mapped beyond 30910005/30910006",
 "APS 221 exposure at 28% (non-breaching) contradicts the CRITICAL risk score and 32x forward DTI — the exposure calculation may not reflect contingent liabilities or cross-default cascade",
 "Loan-level details (tranche expiry, payment schedule, cross-default triggers) explicitly noted as absent — Trajectory's 82-day income expiry and AUD 125,400 scheduled payments lack corresponding TRBK facility records",
 "Signal quality mismatch: rpt1Success and palSuccess both true with pattern confidence 0.46, but 'signal: unclear' prevents attributing CRITICAL to a specific driver"
 ],
 "reasoning": "CRITICAL risk and a deteriorating forward DTI are unmoored from graph findings (1 node, non-breaching exposure); absent loan facility records and an incomplete guarantor/trust network prevent validating whether exposure cascade or cross-default mechanics justify the severity classification."
}

The routing decision: - Confidence stayed at 0.58, below 0.70, on both attempts, and the exposure figure stayed at the same correct AUD 2.1M on both attempts too - Maximum 2 re-queries reached. The pipeline does not loop forever. It proceeds anyway to Human Approval, carrying the gaps forward rather than blocking - The honest gap here isn’t “the LLM made something up.” It’s that this customer’s CRITICAL classification is genuinely driven by Pattern and Trajectory (the under-collateralized loan, the income-expiry DTI spike), not by the relationship graph, and the relationship graph’s own evidence (a clean, real 28%) can’t explain that on its own. Reflection correctly refuses to paper over that mismatch.

Why this matters: Reflection is the only agent that looks at the entire pipeline’s output holistically. Here, it correctly distinguishes “this signal is genuinely clean” from “this signal explains the whole risk picture,” and won’t let a re-query manufacture false agreement between the two just to clear the confidence threshold.

Agent 5: Human-in-the-Loop Approval (HITL)

Purpose: Mandatory human checkpoint. No risk brief reaches the customer file without a human reviewing the evidence first.

The problem it solves: APRA CPS 230 (Operational Resilience) requires that AI systems used in credit risk decisions operate as co-pilots, not autopilots. The risk officer must see the evidence and approve before the final brief is sealed.

How it works:

When Reflection says “proceed,” LangGraph halts the pipeline using interruptBefore: ['humanApproval']. The pipeline is paused. The state is persisted to PostgreSQL, which means the pause survives a server restart. The risk officer is notified in the UI that the pipeline is waiting for their review.

The risk officer sees: - Pattern findings: RPT-1 score, PAL anomaly counts, LLM anomalies - Trajectory: current DTI, forward DTI, days to income expiry - Relationship: the visual graph of connected entities with exposure amounts - Reflection gaps: explicitly what the AI was uncertain about

They click Approve. The pipeline resumes. Synthesis runs. The brief is sealed with approvedBy: "risk.officer@bank.com.au".

If HITL is disabled (for demo or low-risk customers), the pipeline runs straight through to Synthesis automatically.

Agent 6: Synthesis Agent

Purpose: Write the APRA-ready risk brief. Combine all four agents’ findings into a single, structured, regulatory-compliant document.

The problem it solves: Four agents have run. Each produced findings in its own format. A risk officer needs one concise brief with clear findings, recommendations, regulatory citations, and an honest statement of what is uncertain. This brief must be good enough to take to a board. It must cite the actual APRA regulations that apply. It must acknowledge what is not yet known.

How it works:

Step 1: Per-signal HANA Vector Search Instead of one generic regulatory query, the Synthesis Agent performs up to four targeted queries against the HANA Vector Engine, one per risk signal: - “DTI ratio 7.2 debt-to-income limit APRA activation” → retrieves APS 220 / DTI Notice clauses - “connected party group exposure APS 221 large exposure” → retrieves APS 221 thresholds - “income contract expiry forward DTI trajectory deteriorating” → retrieves forward assessment requirements - “CPS 230 operational resilience AI model governance audit trail” → retrieves CPS 230 obligations

The retrieved chunks are deduplicated and capped at 7 to stay within the token budget.

Step 2: LLM Synthesis (Claude Haiku, maxTokens: 2500) All four agents’ outputs, plus the retrieved APRA regulatory text, are sent to Claude Haiku with a structured system prompt. The LLM produces a JSON risk brief. Findings are constrained to 20 words each (precision over prose), with one regulatory standard and one evidence source per finding.

Step 3: Deterministic Guardrails The apraReady flag is NOT decided by the LLM. It is calculated deterministically from four conditions: confidence at or above 0.70, Reflection passed, regulatory docs retrieved, no regulatory context failure. This prevents the LLM from deciding its own work is ready.

Step 4: Claim-Source Overlap Check (RAGAS-inspired, not the RAGAS library) A cosine-similarity check measures how much the LLM’s findings overlap with the retrieved regulatory text. Low overlap (below 30%) means the LLM may be relying on training data, or, as in this run, on an unverified claim from an earlier agent, rather than the retrieved documents. This is flagged in the uncertainty section.

Step 5: Persist to HANA The risk assessment is written to bankingsentinel.RiskAssessments. Token counts and cost are written to bankingsentinel.AuditLog. Both are permanent records under CPS 230.

For 30100003, the produced brief (live run, post-fix):

{
 "riskScore": 87,
 "riskLevel": "CRITICAL",
 "confidence": 0.46,
 "findings": [
 {
 "finding": "Forward DTI 32.05x projected post-income expiry in 82 days; 301% above APRA limit.",
 "standard": "DTI_NOTICE",
 "severity": "HIGH",
 "evidenceSource": "trajectory",
 "confidence": 0.46
 },
 {
 "finding": "Loan L-004 AUD 2.1M exceeds collateral value AUD 1.48M by AUD 620K (LVR breach).",
 "standard": "APS221",
 "severity": "HIGH",
 "evidenceSource": "pattern",
 "confidence": 0.72
 },
 {
 "finding": "Income contract expires in 82 days; primary servicing income at imminent risk.",
 "standard": "DTI_NOTICE",
 "severity": "HIGH",
 "evidenceSource": "trajectory",
 "confidence": 0.46
 },
 {
 "finding": "APS 221 exposure 28% non-breaching contradicts CRITICAL risk score; signal driver unclear.",
 "standard": "APS221",
 "severity": "MEDIUM",
 "evidenceSource": "reflection",
 "confidence": 0.46
 },
 {
 "finding": "Graph traversal incomplete; guarantor network, cross-default triggers, loan facility records absent.",
 "standard": "APS221",
 "severity": "MEDIUM",
 "evidenceSource": "reflection",
 "confidence": 0.58
 }
 ],
 "recommendations": [
 "Urgent loan-level facility query to validate tranche expiry, cross-default mechanics, and payment schedule alignment with the income expiry window.",
 "Expand guarantor/trust network traversal to map contingent liabilities and cascade risk beyond the current 1-node graph.",
 "Require customer income renewal evidence or alternative servicing capacity documentation before the 82-day expiry."
 ],
 "regulatoryRefs": ["DTI_NOTICE", "APS221"],
 "uncertainties": [
 "Loan facility records missing; cannot validate the 82-day income expiry or AUD 125,400 scheduled payment timing.",
 "Cross-default clause details absent; exposure cascade risk to guarantor 30910005 and family trust member 30910006 unquantified.",
 "Signal driver unresolved: rpt1Conf 0.46 with a CRITICAL classification is unmoored from APS 221 non-breach (28%) and 0/7 PAL anomalies.",
 "CPS 230 guardrail: low claim-source overlap (10%) — findings warrant manual review"
 ],
 "apraReady": false
}

Notice what Finding 4 is actually saying: the APS 221 exposure genuinely doesn’t breach (28%, correct, verified), and that genuinely does sit next to a CRITICAL score, because the CRITICAL classification is driven by Trajectory and Pattern (the income-expiry DTI spike, the under-collateralized loan), not by group exposure at all. The brief doesn’t force these into false agreement. It states the real mismatch plainly, flags a 10% claim-source overlap, and sets apraReady: false. That’s the deterministic guardrail (Step 3) working as designed: a brief that’s honest about which of its own findings disagree, rather than one that resolves the disagreement by inventing a number nobody asked for.

7. A Real Example: Customer 30100003

Let us trace the full pipeline from the moment the query is entered to the moment the risk brief appears on screen. This is a live run against the corrected exposure_calculator (see Agent 3), with HITL off (auto-advance through human approval).

The query: “Analyse credit risk for customer 30100003”

Who is 30100003 A retail customer with one business loan (L-004, AUD 2.1 million, retail property sector). Annual income AUD 291,667 from a contract expiring 2026-09-15, 82 days from this run. Current DTI is 7.20 times, already flagged in BCA_DTI as an active breach (BREACH_FLAG: true, dated 2025-08-10). On the surface this already looks concerning. What Banking Sentinel adds is how much worse it gets at income expiry, and, just as important, an honest account of which of its own signals do and don’t agree.

The pipeline execution, phase sequence (real run, total 67.0s):

Phase What happened

Intake	Classifies RISK_ANALYSIS, customerId=30100003
Pattern	RPT-1 → CRITICAL, confidence 0.46, score 87. Isolation Forest (scikit) → 0/7 outliers. LLM → 2 anomalies (L-004 under-collateralized by AUD 620K). Combined: score 87, CRITICAL, routes to high_risk.
Trajectory	Current DTI 7.20x. Forward DTI (income-expiry projection): 32.05x, 301% above the APRA 8x limit. Rate-stress DTI (independent +3% buffer check): 7.42x. Forward position: DETERIORATING. 4 conflicting signals raised.
Relationship (pass 1)	Graph traversal: 1 node, 0 edges (no BUT050 relationship row exists). Exposure calculator (via `BCA_GUARANTOR`, correctly scoped to this group): AUD 2.1M, 28% of APS 221 limit. Confidence 0.95.
Reflection (attempt 1)	Confidence 0.58, below the 0.70 threshold. 5 gaps raised, most pointed: a CRITICAL Pattern score next to a clean 28% exposure reading isn’t explained by the graph yet. Routes to re-query.
Relationship (pass 2, re-query)	Re-traversal still finds 0 new edges, but adds a real fact: guarantor 30910005 (Rose Courtney) is connected to family trust member 30910006. Exposure stays the same, correct AUD 2.1M, 28%. Confidence 0.72.
Reflection (attempt 2)	Confidence 0.58, unchanged. 4 gaps, all converging on the same honest point: the CRITICAL classification comes from Pattern and Trajectory, not from group exposure, and the relationship graph can’t be made to explain it. Maximum re-queries (2) reached, proceeds to Human Approval anyway, carrying the gaps forward.
Human Approval	HITL off for this run, auto-advances.
Synthesis	4 HANA Vector queries fire; 7 APRA regulatory chunks retrieved. Claude Haiku writes the brief. Claim-source overlap: 10% (low). Deterministic `apraReady` check: false.
Persist	Written to `RiskAssessments` and `AuditLog` in HANA. Risk brief delivered via SSE.

Total pipeline time: 67.0 seconds (HITL off) Total cost: AUD 0.0025 Tokens consumed: 2,919 input / 694 output

What the pipeline found that a scorecard would have missed: 1. The income contract expires in 82 days. Forward DTI rockets to 32.05x, 301% above the APRA limit. 2. Loan L-004 is under-collateralized by AUD 620,000, a security deficiency a single DTI number wouldn’t surface. 3. The relationship graph genuinely has no edge for this customer’s guarantor relationship. It only surfaces via a separate table, not the graph traversal tool. 4. The CRITICAL classification doesn’t come from group exposure at all, it comes from income expiry and under-collateralization, and the brief says so plainly rather than forcing every signal to agree with the headline score. 5. The risk brief explicitly says what it does not know: loan-level facility records, cross-default exposure to the guarantor and trust member, and why a CRITICAL score sits next to a clean exposure reading.

8. Regulatory Compliance by Design

Banking Sentinel is built to comply with three APRA standards. Every design decision traces back to a specific regulatory requirement.

APRA APS 221: Large Exposures

APS 221 requires banks to aggregate exposure across connected parties and report when the total exceeds defined thresholds. The Relationship Agent exists solely to implement APS 221. Every graph traversal, every exposure calculation, every threshold check is an APS 221 obligation expressed in code.

APRA CPS 230: Operational Resilience

CPS 230 requires that AI systems used in risk decisions include human oversight, maintain audit trails, and survive operational disruptions. Three system design decisions implement this directly:

Human-in-the-Loop interrupt: every material risk analysis pauses for human approval before the final brief is sealed
PostgreSQL state persistence: the pipeline state survives CF restarts; an approval given before a deployment is not lost
AuditLog: every pipeline run writes token counts, latency, model used, and cost to a permanent HANA table. The risk officer can reconstruct exactly what the AI did and why, months later.

APRA DTI Notice: Debt-to-Income Ratio

The DTI Notice sets the threshold above which high-DTI lending requires additional oversight. Banking Sentinel reads this threshold dynamically from RegulatoryThresholds. When APRA changes its guidance, the threshold changes in the database. No code deployment required. The next pipeline run immediately reflects the new position.

How the threshold actually changes: a real PDF upload, not a config flag. POST /a2a/sync-apra accepts a real APRA PDF (by URL or base64) and runs it through a genuine RAG ingestion pipeline:

Extract: pdf-parse pulls the raw text out of the document.
Chunk: an 800-character sliding window with 100-character overlap, so a sentence that spans a chunk boundary (e.g. “APS 221 requires…”) doesn’t lose its meaning at the seam.
Embed: each chunk goes through OpenAI’s text-embedding-3-small (the same model Synthesis uses for retrieval, so the cosine-similarity comparison is apples-to-apples) and is stored in bankingsentinel.RegulatoryDocuments, a real HANA Vector Engine table, not an in-memory cache.
Parse the actual new limit out of the text. For a DTI_NOTICE upload specifically, a small set of regex patterns (DTI ≥ 6, “DTI ratio greater than or equal to six times”, “debt-to-income … 6 times”, “DTI limit of 6”, and so on) extracts the real numeric threshold from the document’s own wording. It isn’t told the number in advance. If a number is found, RegulatoryThresholds.LIMIT_PCT is updated to that exact value; if parsing fails, it says so explicitly and leaves the threshold untouched rather than guessing.
Replace, don’t accumulate: uploading a new DTI_NOTICE deletes the previous notice’s chunks first, so Synthesis’s vector search always retrieves the current regulatory position, not a mix of old and new guidance.

The risk officer’s experience: upload the new APRA notice once. The system reads its own new threshold out of the document, updates the live regulatory position, and replaces its own knowledge base. The very next analyseRisk call sees the new limit and the new source text, with zero deployment in between.

9. What the Risk Officer Sees

The Banking Sentinel UI displays the pipeline running in real time via Server-Sent Events (SSE). As each agent completes, its output appears on screen, bolded and populated.

The dashboard shows (live values for the 30100003 run above): - Risk Score: 87 / 100, CRITICAL - Pattern Signal: unclear (2 anomalies) - RPT-1: CRITICAL, 46% confidence - Anomaly Detection (scikit-learn): 0 / 7 payment rows flagged as outliers. This dashboard row shows whichever engine actually ran; it’s labelled “PAL” only when ANOMALY_ENGINE=pal is set and the HANA PAL service genuinely executed - Relationship Graph: interactive canvas; first pass 1 node / 0 edges, re-query pass still 1 node, adds the family-trust link to 30910006 without changing the exposure figure - Group Exposure: AUD 2,100,000, 28% of the APS 221 limit, consistent across both passes - Trajectory: current DTI 7.20x → forward DTI 32.05x (in 82 days); rate-stress DTI 7.42x - Reflection: confidence 0.58 (both attempts), 5 then 4 gaps, max re-queries reached - HITL Status: auto-approved (HITL off) for this run - Synthesis: full risk brief with findings, recommendations, regulatory refs, uncertainties; apraReady: false - Audit: cost AUD 0.0025, latency 67.0s, tokens 3,613 total (2,919 in / 694 out)

The report page merges all of this into a single printable brief. Every View Details panel shows the same data as the report, so what the risk officer approves is exactly what goes into the permanent record.

10. Key Design Decisions and Lessons

1. Every AI call has a named pattern

There are no generic LLM calls. Every call is one of: intent classification (Intake), narrative anomaly detection (Pattern), quality self-evaluation (Reflection), ReAct tool-use loop (Relationship), or regulatory synthesis (Synthesis). When something breaks, you know exactly which pattern broke and why.

2. The APRA threshold is never hardcoded

Every agent that needs the DTI threshold reads it from RegulatoryThresholds at runtime. When the APRA Notice is applied in the UI, the threshold changes. The next run of the pipeline reflects it immediately. No deployment, no code change.

3. LangGraph state fields must be declared

LangGraph silently drops state fields that are not declared in Annotation.Root. This caused three bugs: reflectionHistory, hitlEnabled, and totalLatencyMs were all silently lost until each was explicitly declared with its reducer type.

4. Reflection must return one new item, not rebuild the full history

The reflectionHistory field uses an append reducer. Each time the node runs, its return value is appended to the existing array. If the node returns [...existingHistory, newItem], the reducer appends the full rebuilt array again, producing duplicates. The fix: return only [newItem] and let the reducer do the accumulation.

5. The Relationship Agent must not re-traverse from arbitrary nodes

Early iterations of the Relationship Agent would, on finding 0 connections for the primary customer, attempt traversals from random other entities. This pulled in completely unrelated connected-party chains and inflated group exposure. The system prompt now explicitly instructs: if SPARQL returns 0 connections, that is expected. Use the guarantor data already returned.

6. AuditLog and state persistence are separate concerns

The graph.updateState() call persists data to the LangGraph checkpoint (PostgreSQL). The logToAuditLog() call writes to HANA. They are independent. If graph.updateState() throws and logToAuditLog() depends on it completing, the audit record is lost. The fix: wrap graph.updateState() in try-catch so logToAuditLog() always runs.

7. A connected entity’s own unrelated obligations are not this group’s exposure

exposure_calculator queried BCA_GUARANTOR filtered only on GUARANTOR_PARTNER, with no check on whose loan was actually being guaranteed. A guarantor connected to one customer’s group can also guarantee loans for entirely unrelated customers elsewhere in the portfolio, and that filter pulled in their entire guarantee book. This inflated reported APS 221 group exposure from a correct AUD 2.1M (28% of the limit) to a false AUD 11.78M (157%) on re-query, and it reproduced identically across two different starting customers who happened to share a guarantor, which is exactly the kind of bug that looks like a coincidence until you check the underlying data twice. The fix: a guarantee only counts toward this group’s exposure when the loan it covers is held by an entity already in the group, not merely guaranteed by one. Being connected to a customer’s group doesn’t mean every other loan that connection backs belongs to that group.

11. What Comes Next

Banking Sentinel is a working prototype built on a SAP BTP trial account. The path to production involves four upgrades, each with a direct SAP equivalent:

Prototype Component Production Replacement

GraphDB sandbox (expires 7 days)	SAP HANA Knowledge Graph Engine
scikit-learn Flask service	SAP HANA PAL Isolation Forest (requires 3 vCPU)
Supabase free tier (pauses)	SAP BTP PostgreSQL Hyperscaler Option
Single demo customer (30100003)	Full portfolio: all BCA_DTI customers

The architecture does not change. The data sources do not change. The Isolation Forest model that runs on scikit-learn is the same algorithm as HANA PAL. The upgrade path is a configuration change, not a rebuild, but it’s worth being precise about what “the same queries work on both” actually means: the traversal semantics carry over, not literal byte-for-byte SQL. Here’s a concrete example for a sample business partner 0001, showing what’s actually run today against GraphDB and the equivalent HANA KGE query it maps to:

Today, SPARQL against GraphDB:

PREFIX bs: <urn:banking-sentinel:>
SELECT DISTINCT partnerId reltyp WHERE {
<urn:banking-sentinel:partner/0001> bs:relatedTo* node .
node bs:partnerId partnerId .
OPTIONAL {
<urn:banking-sentinel:partner/0001> rel node .
BIND(STRAFTER(STR(rel), "relatedTo/") AS reltyp)
}
}

Production target, HANA KGE, GRAPH_TABLE on a BP_RELATIONSHIP_GRAPH workspace (BUT050 rows as edges, BusinessPartners rows as vertices, the mapping described in relationship-agent.js😞

SELECT connected_partner_id, rel_type
FROM GRAPH_TABLE (BP_RELATIONSHIP_GRAPH
 MATCH (a:BusinessPartner)-[e:RELATED_TO*]->(b:BusinessPartner)
 WHERE a.partner_id = '0001'
 COLUMNS (
 b.partner_id AS connected_partner_id,
 e.rel_type AS rel_type
 )
)

Both express the same thing: variable-depth traversal from one business partner outward, returning every connected partner and the relationship type linking them. The vertex/edge mapping (BUT050 to graph edges, BusinessPartners to graph vertices) is the same in both. This KGE query is the documented target shape, not a verified one. HANA KGE isn’t available on the BTP trial tier this prototype runs on, so it has never actually executed against a live KGE instance. The honest claim is: the traversal logic and data model translate directly; the literal SQL above has not been run.

Summary

Banking Sentinel is a complete, regulation-compliant, multi-agent AI risk system on a mixed stack with an explicit SAP boundary. SAP HANA Cloud, SAP CAP, and SAP RPT-1 carry the data and tabular-AI layer end to end, proven and ready to swap toward HANA PAL and HANA Knowledge Graph Engine in production. The reasoning and orchestration layer is non-SAP today because AI Core isn’t available on the trial tier this runs on, not because it was found wanting. Knowing exactly where that line sits is the more credible story.

Seven agents. Four risk dimensions. Three APRA standards. One risk officer decision. Under 80 seconds.

The customer who already shows a DTI breach on a scorecard, 7.20x, is actually a CRITICAL risk customer with a forward DTI of 32.05x at income expiry in 82 days, a loan under-collateralized by AUD 620,000, a connected-party graph with no relationship edge to show for it, and a CRITICAL classification that the brief is honest doesn’t come from group exposure at all, because group exposure (AUD 2.1M, 28%, stable across a re-query) genuinely doesn’t explain it.

Banking Sentinel does not approve or reject. It finds. It explains. It acknowledges what it does not know. And it gives the risk officer everything they need to make a confident, documented, APRA-compliant decision.

Built on: SAP BTP Cloud Foundry, SAP HANA Cloud, SAP CAP, SAP RPT-1, LangGraph, Claude Haiku 4.5, GraphDB / HANA KGE, scikit-learn / HANA PAL, Langfuse, Solace

APRA Standards: APS 221 (Large Exposures), CPS 230 (Operational Resilience), DTI Notice (Debt-to-Income)

Natural Language Queries for SAP CAP via MCP: The LLM Translates, CDS Executes

2026-06-25T03:37:23.340000+02:00

An MCP server that turns plain-English questions into CDS queries against your SAP CAP database layer, using schema annotations to resolve JOINs and disambiguate values.

GitHub · npm · MCP Registry

If you work with SAP CAP projects: a business question comes in, you open your SQL editor, figure out which tables hold the answer, and work out the JOINs and filter conditions. Ask a slightly different question and you start over.

This MCP server lets you ask the question directly instead.

Which customers have a DTI ratio above 5?

And get this back:

Results: 3 rows

Partner    : 30100003
DTI Ratio  : 7.20
Customer   : Domestic Customer AU 3

Partner    : 30100001
DTI Ratio  : 5.80
Customer   : Domestic Customer AU 1

Partner    : 30100004
DTI Ratio  : 5.40
Customer   : Domestic Customer AU 4

That's what cds-db-nlquery-mcp does. It's an MCP server that sits on top of your SAP CAP project and lets you query your database-layer entities (the ones defined in db/schema.cds, not your OData service layer) in natural language, from Claude Code, Claude Desktop, or any MCP-compatible host.

Here's how it works, why it's architected this way, and three real examples against a live HANA Cloud schema.

How It Works, At a Glance

 Your question (plain English)
        │
        ▼
 ┌────────────────────────┐
 │ Stage 1: LLM            │  reads your CDS schema (labels, associations,
 │ Question → Descriptor   │  @Common.Text, enums) → outputs JSON only:
 └─────────┬───────────────┘  { entity, select, where, valCol, limit }
           │  JSON descriptor
           ▼
 ┌────────────────────────┐
 │ Stage 2: CDS            │  descriptor → CQN → real SQL JOINs,
 │ Descriptor → SQL        │  generated from association metadata,
 └─────────┬───────────────┘  not guessed by the LLM
           │  rows from HANA
           ▼
 ┌────────────────────────┐
 │ Stage 3: Answer         │  MCP client renders the rows, or hands them
 │ Rows → Plain English    │  to a second LLM call to phrase the answer
 └────────────────────────┘

   The LLM never touches SQL. CDS never touches your question.

Why This Isn't "LLM Writes SQL"

One common pattern for natural-language-to-SQL works by dumping the whole database schema into a prompt, asking the LLM to write SQL, and running whatever comes back. The LLM has to get table names, JOIN syntax, and HANA-specific SQL right in one shot, with no framework checking its work.

This package splits the problem in two:

The LLM's only job is translation. It reads your CDS schema and turns a question into a small JSON descriptor: entity, columns, filters. It never writes SQL.
The CDS framework's only job is execution. It turns that descriptor into a CQN query (CDS's own query representation) using association-path expressions, and lets CDS, not the LLM, not hand-written SQL, generate the actual SQL JOINs that HANA executes.

That division matters: two common failure modes are doing JOINs in JavaScript after fetching too much data, or trusting the LLM to write syntactically valid HANA SQL from scratch. This server avoids both. There's no JavaScript-side join, no post-fetch filtering. WHERE, ORDER BY, and LIMIT are all pushed down to HANA in a single round-trip per question.

Three-Stage Architecture

You: "Show me active loans for customers in the mining sector,
      with the borrower's name and loan amount"

Stage 1: Question → JSON Descriptor

At startup, the server loads your full CDS model and builds a compact schema description: entity names, columns with types, labels, enums, @Common.Text references, and association paths. That schema text plus your question goes to a fast, cheap model tier (claude-haiku-4-5-20251001, gpt-4o-mini, or any configured provider). The LLM responds with a descriptor, not SQL:

{
  "entity": "Loans",
  "select": ["LOAN_ID", "AMOUNT", "customer.BU_SORT1", "status.TEXT"],
  "where": [
    { "col": "customer.SECTOR_CODE", "op": "=", "val": "MINING" },
    { "col": "status.TEXT", "op": "like", "val": "Active" }
  ],
  "limit": 50
}

This is a cheap LLM call, a structured-output translation task, not a reasoning task. The model isn't answering your question; it's mapping it onto the schema vocabulary it was given.

Stage 2: Descriptor → CQN → SQL (CDS Generates the JOINs, Not the LLM)

The server takes that descriptor and builds one CDS CQN query. customer.BU_SORT1 and status.TEXT are CDS association paths. The server resolves them against the schema's join metadata and CDS compiles them into real SQL JOINs:

SELECT
  L.LOAN_ID,
  L.AMOUNT,
  BP.BU_SORT1   AS customer_BU_SORT1,
  LSC.TEXT      AS status_TEXT
FROM bankingsentinel_Loans L
INNER JOIN bankingsentinel_BusinessPartners BP  ON BP.PARTNER = L.PARTNER
LEFT  JOIN bankingsentinel_LoanStatusCodes  LSC ON LSC.CODE    = L.STATUS
WHERE UPPER(BP.SECTOR_CODE) = 'MINING'
  AND UPPER(LSC.TEXT) LIKE '%ACTIVE%'
LIMIT 50

The JOINs are real, generated by CDS from association metadata you already declared in your schema, not reconstructed from scratch by an LLM guessing at foreign keys.

Stage 3: Results → Answer

The rows come back from cds.run() as plain objects. Your MCP client (Claude Code, Claude Desktop, etc.) renders them, or, as in the Banking Sentinel example later, hands them to a second, separate LLM call whose only job is to phrase the answer in plain English.

Wait, Is That Safe?

Right question. The server only ever issues SELECT. There is no code path that builds an INSERT, UPDATE, or DELETE. Beyond that, there are three independent layers, all enforced server-side, none of them optional:

Database-level: point MCP_DB_USER/MCP_DB_PASSWORD at a dedicated read-only HANA user. If the framework had a bug, HANA itself would still reject a write.
Entity allowlist (MCP_ALLOWED_ENTITIES😞 restricts which entities are queryable at all. This is enforced on the entity you asked for and on every entity reached through an association path, so allowlisting BCA_DTI but not BusinessPartners blocks customer.BU_SORT1 from being selected at all, closing the obvious bypass-via-JOIN hole.
Column blocklist (MCP_BLOCKED_COLUMNS😞 strips named columns (e.g. PASSWORD, EMBEDDING, SSN) before the query is even built. They're never sent to HANA, not fetched-then-redacted.

The one thing worth saying plainly, because the README says it plainly: this bypasses your CAP service-layer @requires/@restrict annotations. It queries db/schema.cds entities directly via cds.run(), not your OData service. If your service layer is where your authorization model lives, that model doesn't apply here. The three controls above are the substitute, not an addition.

For a quick demo, start with none of them and everything is queryable. For anything pointed at real data, set all three.

The Real Lever: Schema Annotations, Not Prompt Engineering

Before the examples, this is the part that actually determines whether your queries come back right: @nlp.label.

The server already reuses your existing @title annotations automatically. If your schema already has Fiori value-help labels, the LLM gets those for free. @nlp.label exists for the cases where @title doesn't fit or isn't disambiguating enough, and it overrides @title when both are present.

Here's a real one from the schema you'll see in the examples below:

@title: 'Partner Type Code'
@NLP.label: 'Partner type code: 1=person, 2=organisation. NOT a name, never use for name lookups'
BU_TYPE : String(2);

Without that label, BU_TYPE is just a two-character string column to the LLM, and "type code" columns get mistaken for name columns constantly, because the LLM has no way to know what the values mean. The label isn't decoration; it's the only channel you have to tell the model what NOT to do with a column. The same mechanism handles join direction (@nlp.joinType: 'LEFT' when cardinality alone is ambiguous) and aliasing (@nlp.alias).

None of this touches your OData service or Fiori UI. @nlp.label is a CDS annotation the server reads at schema-load time and nothing else consumes.

Configuration

npm install @shahid.la/cds-db-nlquery-mcp

Create .mcp.json in your CAP project root:

{
  "mcpServers": {
    "cds-db-nlquery-mcp": {
      "command": "npx",
      "args": ["-y", "@shahid.la/cds-db-nlquery-mcp"],
      "cwd": "/absolute/path/to/your/cap/project",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "ANTHROPIC_MODEL": "claude-haiku-4-5-20251001"
      }
    }
  }
}

Open the project in an MCP-aware client and ask a question. LLM_PROVIDER auto-detects from whichever API key is set, so for a quick start you only need the key.

Production env vars:

Variable Default Purpose

`MCP_ALLOWED_ENTITIES`	all entities	Comma-separated entity allowlist, enforced on JOINs too
`MCP_BLOCKED_COLUMNS`	none	Columns stripped before the query is built
`MCP_MAX_ROWS`	500	Hard SQL `LIMIT` cap, server-side
`MCP_DB_USER` / `MCP_DB_PASSWORD`	inherits app's DB user	Run as a separate, ideally read-only, HANA user
`MCP_MODEL_PATH`	`db`	Where your CDS model lives, if not the default `db/`

LLM providers, today: Anthropic and OpenAI are first-class (ANTHROPIC_API_KEY / OPENAI_API_KEY). Everything else, Azure OpenAI, Groq, Ollama, local models, works through OPENAI_BASE_URL pointed at any OpenAI-compatible endpoint, not through a dedicated integration.

What the Server Reads From Your CDS Schema

Beyond @title/@nlp.label (covered above), several more things already in your schema do the rest of the work, none of them new annotations you'd have to add just for this:

Associations: drive every JOIN. Cardinality (to-many vs to-one) decides LEFT vs INNER automatically, and which expand/hierarchy shapes are even valid.
@Common.Text and @Common.ValueList: the standard SAP value-help patterns, reused so the LLM filters on human text instead of guessing codes, whether it's a small fixed enum or a large lookup table.
Native CDS enum: surfaced to the LLM as name="value" pairs, and translated back (STATUS_text) automatically in every result row, including inside nested expand results, recursively.
Calculated-on-read elements (FULL = FIRST || ' ' || LAST😞 selectable like any stored column. The server substitutes the underlying expression itself rather than assuming the database materialized it as a physical column (confirmed it doesn't, on HANA).
@assert.range: surfaced as a sanity-bound hint, so the LLM can catch a likely unit/scale mismatch (a 0-1 ratio vs. a 0-100 percentage) before it emits a filter that trivially returns zero rows.
@CDS.search and @CDS.valid.from/@CDS.valid.to: free-text search columns and temporal entities, both read directly from annotations you'd already have for Fiori search bars and time-sliced data.

This is why it doesn't feel like a generic SQL wrapper bolted onto your project: it's reading the same metadata your CDS model already carries for OData, Fiori value-help, and UI labels, just pointed at a different consumer.

To make this concrete, here's the exact text buildSchemaPrompt() produces for the capability demo schema. This is what the LLM planner sees for every question:

Customers [Customers]
  columns: ID:String, NAME:String["Customer Name"], NOTES:String, FIRST:String, LAST:String, FULL:String[calculated]
  joins:   "orders"→Orders(ID=CUSTOMER_ID,LEFT,toMany)
  searchable: NAME, NOTES
Orders [Orders]
  columns: ID:String, CUSTOMER_ID:String, AMOUNT:Decimal{pairs with CURRENCY: always select both together}, CURRENCY:String["Currency code (e.g. USD, EUR). A text code, never numeric. Never SUM/AVG/MIN/MAX this column, aggregate AMOUNT instead."], STATUS:String{values: open="O",closed="C". Use the raw value in filters. Selecting "STATUS" alone ALSO gets you a "STATUS_text" business-term field in every result row, with NO extra effort: do not select "STATUS_text" yourself (it is not a real column, you cannot select it, it just appears in the output), and do not add your own "caseWhen" to relabel "STATUS" (you would create a duplicate/conflicting column with the one already added for you)}, ORDER_DATE:Date
  joins:   "customer"→Customers(CUSTOMER_ID=ID,INNER), "items"→OrderItems(ID=ORDER_ID,LEFT,toMany)
OrderItems [OrderItems]
  columns: ID:String, ORDER_ID:String, PRODUCT_ID:String, PRODUCT:String, QTY:Integer, STATUS:String{values: pending="P",shipped="S". Use the raw value in filters. Selecting "STATUS" alone ALSO gets you a "STATUS_text" business-term field in every result row, with NO extra effort: do not select "STATUS_text" yourself (it is not a real column, you cannot select it, it just appears in the output), and do not add your own "caseWhen" to relabel "STATUS" (you would create a duplicate/conflicting column with the one already added for you)}
  joins:   "product"→Products(PRODUCT_ID=ID,INNER)
Products [Products]
  columns: ID:String, NAME:String, SECRET:String, STATUS:String{values: active="A",discontinued="D". Use the raw value in filters. Selecting "STATUS" alone ALSO gets you a "STATUS_text" business-term field in every result row, with NO extra effort: do not select "STATUS_text" yourself (it is not a real column, you cannot select it, it just appears in the output), and do not add your own "caseWhen" to relabel "STATUS" (you would create a duplicate/conflicting column with the one already added for you)}
Accounts [Accounts]
  columns: ID:String, NAME:String, PARENT_ID:String, STATUS:String{values: active="A",closed="X". Use the raw value in filters. Selecting "STATUS" alone ALSO gets you a "STATUS_text" business-term field in every result row, with NO extra effort: do not select "STATUS_text" yourself (it is not a real column, you cannot select it, it just appears in the output), and do not add your own "caseWhen" to relabel "STATUS" (you would create a duplicate/conflicting column with the one already added for you)}
  joins:   "parent"→Accounts(PARENT_ID=ID,INNER){self-referencing: hierarchy}, "children"→Accounts(ID=PARENT_ID,LEFT,toMany){self-referencing: hierarchy}
Sectors [Sectors]
  columns: CODE:String, DESCRIPTION:String
Loans [Loans]
  columns: ID:String, DTI:Decimal[0..50], SECTOR:String{readable text available via "sector.DESCRIPTION". Include it in select to show the human-readable value, AND use this path (not the raw "SECTOR" column) when the question filters by a human term like "active"/"closed"/"overdue" rather than a raw code}
  joins:   "sector"→Sectors(SECTOR=CODE,INNER)
WorkAssignments [WorkAssignments] [temporal: valid from validFrom to validTo]
  columns: ID:String, EMPLOYEE:String, ROLE:String, validFrom:Date, validTo:Date

Entity names, column types, NLP labels, enum values with the auto-STATUS_text instruction, join cardinality, the {self-referencing: hierarchy} marker that enables hierarchy traversal, and the [temporal: ...] marker that enables asOf time-travel reads. The LLM doesn't infer any of this from column names. It reads it directly from what the schema reader extracted.

Three Real Examples

These run against the actual schema and seed data of Banking Sentinel (writeup), a demo SAP CAP + HANA Cloud project I use to exercise this package against a real, non-trivial schema (18 entities, multi-hop associations, coded value-help tables). Every descriptor and result below reflects that real schema. Nothing is invented for the post.

Example 1: Simple Filter Across One Association

Question: "Which customers have a DTI ratio above 5?"

Schema (the relevant slice):

entity BCA_DTI {
  key PARTNER : String(10);
  DTI_RATIO   : Decimal(5,2);

  customer : Association to BusinessPartners on customer.PARTNER = PARTNER;
}

@NLP.label: 'Customers and business partners. Demo borrowers: 301xxxx, guarantors: 309xxxx'
entity BusinessPartners {
  key PARTNER : String(10);
  @title: 'Customer / Business Partner Name'
  BU_SORT1    : String(50);
}

Descriptor the LLM returns:

{
  "entity": "BCA_DTI",
  "select": ["PARTNER", "DTI_RATIO", "customer.BU_SORT1"],
  "where": [{ "col": "DTI_RATIO", "op": ">", "val": 5 }],
  "orderBy": "DTI_RATIO",
  "orderDir": "DESC",
  "limit": 20
}

Result, against the live database:

Results: 3 rows

Partner    : 30100003
DTI Ratio  : 7.20
Customer   : Domestic Customer AU 3

Partner    : 30100001
DTI Ratio  : 5.80
Customer   : Domestic Customer AU 1

Partner    : 30100004
DTI Ratio  : 5.40
Customer   : Domestic Customer AU 4

One association (customer), one JOIN, one filter. This is the floor. Every query, however complex, starts from this same mechanism.

Example 2: Coded Values via `@Common.Text` (Not Guessing the Raw Code)

Question: "Show me active loans for customers in the mining sector, with the borrower's name and loan amount."

This question has a trap: "active" and "mining sector" are both human terms over coded columns. Loans.STATUS is stored as a single character ('A'/'C'), not the word "active." If the LLM guessed at the raw code, it would be wrong as often as it was right.

Schema:

entity Loans {
  key LOAN_ID   : String(15);
  PARTNER       : String(10);
  AMOUNT        : Decimal(15,2);
  @Common.Text: status.TEXT
  STATUS        : String(1);

  customer : Association to BusinessPartners on customer.PARTNER = PARTNER;
  status   : Association to LoanStatusCodes  on status.CODE     = STATUS;
}

// Adding a new status is a data INSERT into this table, never a schema/code change.
entity LoanStatusCodes {
  key CODE : String(1);
  TEXT     : String(20);
}

entity BusinessPartners {
  key PARTNER  : String(10);
  BU_SORT1     : String(50);
  SECTOR_CODE  : String(20);   // RETAIL_PROP, MINING, AGRICULTURE, ...
}

@Common.Text: status.TEXT is the standard SAP value-help pattern, the same one Fiori uses to show "Active" in a dropdown while storing 'A'. The schema reader tells the LLM this path exists; the system prompt instructs it to filter on status.TEXT directly rather than invent a raw code.

Descriptor the LLM returns:

{
  "entity": "Loans",
  "select": ["LOAN_ID", "AMOUNT", "customer.BU_SORT1", "status.TEXT"],
  "where": [
    { "col": "customer.SECTOR_CODE", "op": "=", "val": "MINING" },
    { "col": "status.TEXT", "op": "like", "val": "Active" }
  ],
  "limit": 50
}

Result:

Results: 1 row

Loan ID    : L-009
Amount     : AUD 3,200,000.00
Customer   : Domestic Customer AU 9
Status     : Active

If the bank adds a new loan status next quarter (PENDING_REVIEW = 'P'), this query keeps working without a code change. It's matching on text, not a hardcoded code the LLM would otherwise have had to memorize.

Example 3: Column-to-Column Comparison Across Two Hops (`valCol`)

Question: "Which loans are under-collateralized, where the pledged collateral is worth less than the loan amount?"

This is qualitatively different from the first two: it's not comparing a column to a value the user typed, it's comparing two columns from different entities to each other. There's no literal to filter on.

Schema:

entity BCA_COLLATERAL {
  key LOAN_ID   : String(15);
  key COLLAT_ID : String(15);
  COLLAT_TYPE   : String(10);   // PROPERTY, VEHICLE, CASH
  VALUE         : Decimal(15,2);

  loan : Association to Loans on loan.LOAN_ID = LOAN_ID;
}

entity Loans {
  key LOAN_ID : String(15);
  AMOUNT      : Decimal(15,2);
  customer    : Association to BusinessPartners on customer.PARTNER = PARTNER;
}

The descriptor format supports valCol for exactly this: comparing a column to another column (a path, possibly through a JOIN) instead of to a literal val:

{
  "entity": "BCA_COLLATERAL",
  "select": ["COLLAT_TYPE", "VALUE", "loan.LOAN_ID", "loan.PARTNER", "loan.customer.BU_SORT1", "loan.AMOUNT"],
  "where": [
    { "col": "VALUE", "op": "<", "valCol": "loan.AMOUNT" }
  ],
  "orderBy": "loan.LOAN_ID",
  "limit": 50
}

loan.customer.BU_SORT1 is a two-hop path (BCA_COLLATERAL → loan → Loans → customer → BusinessPartners), resolved in the same single query, no extra round-trip. The generated WHERE clause is WHERE COLLAT.VALUE < L.AMOUNT, a real cross-table comparison, not two separate queries reconciled in JavaScript.

Raw result: 10 rows. Worth pausing on why it's 10 and not fewer: the comparison is per pledged asset, not per loan. A loan secured by both a property and a cash deposit produces two collateral rows, and each is compared to the full loan amount individually. That's the literal, correct answer to "which pledged assets are worth less than the loan." It just means a multi-asset loan can appear more than once, even when its combined collateral would be adequate.

That's exactly where Stage 3 earns its place. The MCP server hands back those 10 flat rows; the second LLM call (the one that turns MCP results into an answer) grouped them by loan and computed the shortfall itself:

10 under-collateralized loan records identified (collateral value < loan amount):

Loan L-004 (Partner: 30100003, Domestic Customer AU 3)
Loan Amount: AUD 2,100,000.00
Total Collateral Value: AUD 1,480,000.00
Shortfall: AUD 620,000.00
Collateral Breakdown:
  Property: AUD 1,200,000.00
  Cash: AUD 280,000.00

Loan L-006 (Partner: 30100005, Domestic Customer AU 5)
Loan Amount: AUD 1,850,000.00
Total Collateral Value: AUD 1,300,000.00
Shortfall: AUD 550,000.00
Collateral Breakdown:
  Property: AUD 1,100,000.00
  Cash: AUD 200,000.00

Loan L-007 (Partner: 30100006, Domestic Customer AU 6)
Loan Amount: AUD 45,000.00
Total Collateral Value: AUD 35,000.00
Shortfall: AUD 10,000.00
Collateral Breakdown:
  Vehicle: AUD 35,000.00

Loan L-009 (Partner: 30100009, Domestic Customer AU 9)
Loan Amount: AUD 3,200,000.00
Total Collateral Value: AUD 2,400,000.00
Shortfall: AUD 800,000.00
Collateral Breakdown:
  Property: AUD 2,000,000.00
  Cash: AUD 400,000.00

[+ 3 more collateral rows across 2 loans from the wider training portfolio, outside the named demo customers]

This example is the most demanding of the three: it resolves a coded value-help table and performs a column-to-column comparison across an association path, which requires the framework, not the LLM, to understand JOIN semantics. And the per-asset-not-per-loan result is itself a useful, honest reminder of what the descriptor format can and can't express today: it has no SUM/GROUP BY, so "is this loan's combined collateral sufficient" is a question for the LLM answering over the raw rows, not something the query itself computes.

Beyond the Three Examples: Four More Capabilities With Real Output

The Banking Sentinel examples cover three patterns: simple filter, coded value-help JOIN, and column-to-column comparison. Here's what else the descriptor format supports, each shown against the capability demo schema with output captured by running node examples/capability-demo/generate.js against a real in-memory database.

Nested Reads

Question: "Orders with their line items nested inside"

{
  "entity": "Orders",
  "select": ["ID", "CUSTOMER_ID"],
  "expand": [{ "assoc": "items", "select": ["PRODUCT", "QTY"] }]
}

Result:

[
  { "ID": "O1", "CUSTOMER_ID": "C1", "items": [{"PRODUCT":"Widget","QTY":10},{"PRODUCT":"Gadget","QTY":5}] },
  { "ID": "O2", "CUSTOMER_ID": "C1", "items": [{"PRODUCT":"Widget","QTY":20}] },
  { "ID": "O3", "CUSTOMER_ID": "C2", "items": [{"PRODUCT":"Gizmo","QTY":3}] },
  { "ID": "O4", "CUSTOMER_ID": "C2", "items": [] },
  ...
]

One query. Each parent row carries its children as a real nested array, not a flattened, duplicated-parent-row JOIN result. expand supports orderBy/limit on the nested side (e.g. "each order's single largest line item by quantity") and nests recursively to any depth.

Recursive Hierarchy

Question: "All descendants of account A1, the full org tree below it"

{
  "entity": "Accounts",
  "select": ["ID", "NAME", "PARENT_ID"],
  "hierarchy": {
    "assoc": "children",
    "direction": "descendants",
    "startWhere": [{ "col": "ID", "op": "=", "val": "A1" }]
  }
}

Result:

ID : A1   Name : Holding Co          Parent : —    Status : active
ID : A2   Name : Regional Division   Parent : A1   Status : active
ID : A3   Name : Local Branch North  Parent : A2   Status : active
ID : A4   Name : Local Branch South  Parent : A2   Status : closed
ID : A5   Name : Sub Branch North-1  Parent : A3   Status : active

Five levels from a single question. The STATUS_text translation (raw "A" to "active", "X" to "closed") applies automatically, including on hierarchy results. A fixed-depth association path (account.parent.parent.NAME) cannot express an unbounded tree walk. hierarchy can, capped by a configurable max depth.

Window Functions

Question: "Each customer's single largest order"

{
  "entity": "Orders",
  "select": ["ID", "CUSTOMER_ID", "AMOUNT"],
  "window": [{ "fn": "rank", "as": "RANK", "partitionBy": ["CUSTOMER_ID"], "orderBy": [{ "col": "AMOUNT", "dir": "DESC" }] }],
  "windowFilter": [{ "col": "RANK", "op": "=", "val": 1 }]
}

CDS generates the subquery wrapping that HAVING alone can't express:

SELECT ID, CUSTOMER_ID, AMOUNT, RANK
FROM (
  SELECT ID, CUSTOMER_ID, AMOUNT,
         rank() OVER (PARTITION BY CUSTOMER_ID ORDER BY AMOUNT DESC) AS RANK
  FROM Orders
) WHERE RANK = 1
LIMIT 50

Result:

ID : O2   Customer : C1 (Acme Corp)    Amount : 2300.50
ID : O4   Customer : C2 (Globex Inc)   Amount : 4200.00
ID : O5   Customer : C3 (Initech)      Amount :  150.00

One row per customer, the actual largest order, not a MAX() that loses the order ID. Running totals, lag/lead, and row_number follow the same pattern.

Time-Travel Reads

Two questions, same entity, different answers:

"What was Alice's role on 2026-02-15?"

{ "entity": "WorkAssignments", "select": ["EMPLOYEE", "ROLE"],
  "where": [{ "col": "EMPLOYEE", "op": "=", "val": "Alice" }],
  "asOf": "2026-02-15" }

→ ROLE: Analyst

"What is Alice's current role?"

{ "entity": "WorkAssignments", "select": ["EMPLOYEE", "ROLE"],
  "where": [{ "col": "EMPLOYEE", "op": "=", "val": "Alice" }] }

→ ROLE: Senior Analyst

@CDS.valid.from/@CDS.valid.to entities work automatically. The server adds the validFrom <= date AND validTo > date filter for asOf, or defaults to now when no date is given. No annotation beyond what you'd already add for Fiori time-sliced data.

Same architectural promise as before: the LLM picks which of these to use and fills in the JSON, CDS turns it into real CQN, the server never writes SQL by hand.

Built by Testing Against Real HANA, Not Just an In-Memory Database

A comprehensive unit test suite (126 tests) passed the entire time these capabilities were broken in a specific, real way. The tests used an in-memory SQLite-style adapter that tolerates things real HANA doesn't. The only way to actually know whether this worked was to deploy the demo schema to a real HANA Cloud instance and run every query against it for real. So that's what I did, repeatedly, across one extended session, and it caught real bugs:

A real NL question, "show me each customer's single largest order," surfaced that expand's orderBy/limit (for "top N per group") wasn't implemented at all. The row cap applied, but nothing sorted first, so the result could silently be an arbitrary order instead of the actual largest one. Fixed by sorting before truncating. That fix, plus the existing enum-to-text translation and blocked-column stripping, all shared one unexamined assumption: each only ever checked Array.isArray() on a nested value. A follow-up systematic audit, deliberately constructing a two-level expand test, not a natural-language question this time, found all three silently skipped a nested value entirely whenever it was a plain object (a to-one association) instead of an array.
A descriptor with an unrecognized field (an LLM wrote {"notExists": "orders"} as a sibling of "where" instead of inside it) was silently ignored rather than rejected. The query ran with no filter applied at all, returning every row instead of failing loudly.
The legacy @SAP/hana-client-based HANA runtime (still the default most CAP+HANA projects use) silently drops the OVER clause from a window-function query. No error, just wrong SQL, until HANA itself throws a syntax error downstream. Confirmed the CQN this package generates is correct per CAP's current standard (the same shape @cap-js/sqlite and the modern @cap-js/hana adapter both render properly). Only the legacy runtime mishandles it. The server now detects which adapter is connected and only restricts behavior on the legacy one; on a modern adapter, the same query just works.
A genuinely production question, Banking Sentinel's own "what is the total loan amount across all customers?", surfaced that the planning LLM occasionally puts a function-call string like "SUM(AMOUNT)" directly into select, instead of using the aggregate field. The column-ref builder then treated the whole string as a literal column name, and HANA rejected it with a cryptic invalid column name: SUM(AMOUNT). A second real failure on the same question widened the same mistake to a full SQL fragment with a trailing alias ("SUM(AMOUNT) AS TOTAL_AMOUNT"), which an exact-match pattern didn't catch. Both are now rejected up front, across every field a column-spec string can appear in (select, where, groupBy, orderBy, having.col, aggregate.col), with a message that names the actual fix, instead of reaching HANA as a cryptic failure or, worse, silently returning a wrong total.

Every one of these was found, root-caused, and fixed by actually deploying examples/capability-demo/'s schema to live HANA and running real queries against it, not by reading the code harder. The four scripts that do this live in that folder in the GitHub repo (they're development/testing tools, not part of the published npm package, npm install only gives you src/), ready to run, not just described:

validate-deployment.js: runs every hand-written descriptor against your deployment and compares rows to the SQLite-generated results.json baseline, no LLM involved. The definitive check for whether execution is correct on your specific backend and adapter.
ask.js: runs a single natural-language question end-to-end through a real LLM against your deployment, useful for questions the pre-built list doesn't cover.
ask-batch.js: runs every pre-built question's natural-language text (not the hand-written descriptor) through a real LLM and compares the result. The script that actually distinguishes "the package is wrong" from "the model picked an odd column," and the one that surfaced real, fixable mistakes across two different models (Claude and DeepSeek).
smoke-test-server.js: unlike the other three (which call internal functions via require()), this spawns src/mcp-server.js as a real child process and drives it through the MCP stdio protocol the same way Claude Code or npx actually would. Used to confirm that what's correct at the library level is also correct at the published-artifact level.

If you're evaluating this for something that matters, don't take the examples above on faith. Clone the repo, deploy examples/capability-demo/ to your own HANA, and run these scripts yourself.

What Happens When the LLM Gets It Wrong

All three examples above are success cases, worth being honest about the failure path too. If the LLM's response doesn't parse as JSON, or comes back without an entity field, the server rejects it outright rather than guessing or silently running a degraded query. The same applies to an entity or column outside MCP_ALLOWED_ENTITIES, or one that doesn't exist in your schema at all. Each produces a clear error back to the MCP client, not a best-effort result you'd have to double-check. There's no fallback path that quietly does something different from what you asked.

When to Use This (and When Not To)

Good fit:

Ad-hoc data exploration during development or support investigations
Audit/compliance spot-checks, e.g. "show me all loans without collateral where LTV exceeds 80%"
Operational questions that change shape every time, so a fixed report doesn't fit

Not a fit:

Anything user-facing: this bypasses @requires/@restrict, use your OData service for that
Scheduled/repeated reporting: this is exploratory, not a BI tool
Any write path: read-only by design, no exceptions

Database compatibility:

Tested on HANA Cloud (BTP) with both adapters CDS supports: @cap-js/hana (all capabilities work, including window functions and viaFiltered-inside-aggregate) and the legacy @SAP/hana-client runtime (those two specific things are rejected with a clear error; everything else works). Not tested on on-premise classic HANA.

Try It

npm install @shahid.la/cds-db-nlquery-mcp

Add the .mcp.json block above, point it at a CAP project with a few @nlp.label annotations, and ask it something you'd otherwise have opened a SQL editor for.

Want to verify all of this yourself before trusting it with something that matters, rather than trusting this post? Clone the repo, deploy examples/capability-demo/'s schema to your own database, and run validate-deployment.js, ask.js, ask-batch.js, and smoke-test-server.js, the same scripts that found and confirmed every fix described above.

Find the project on GitHub, npm, and the MCP Registry .

Feedback, issues, and PRs welcome, especially real-world schema patterns and annotation edge cases.

Bringing Domain Intelligence into SAP Joule

2026-07-01T23:25:41.416000+02:00

Why “domain intelligence” is the missing piece

Foundation models are impressive generalists, but enterprise questions are specific. “Which quotation gives us the best win/win with this customer?” is not answered by general world knowledge. It is answered by your master data, your pricing logic, and the relationships between them.

That is where two capabilities on SAP Business AI Platform come together. First, a Knowledge Graph captures your domain as connected, machine-readable facts with explicit semantics. Second, the A2A protocol lets a custom agent that reasons over that graph plug directly into Joule, so the intelligence shows up where users already work.

The picture below shows how the pieces fit: Joule stays the orchestrator, a pro-code agent does the specialized work, and the SAP HANA Cloud Knowledge Graph engine holds the domain intelligence the agent draws on.

Joule orchestrates; the pro-code agent reasons; the Knowledge Graph engine holds your domain intelligence.

Step 1: Capture domain knowledge as an Ontology and Knowledge Graph

A Knowledge Graph is only as smart as the ontology behind it. The ontology is the semantic model: it names your entities, describes their attributes, and, crucially, records how they relate. That semantic layer is what turns raw content into meaning a machine can reason over.

Importantly, your source does not have to be a database. The SAP HANA Cloud Knowledge Graph samples cover two paths. In the first, unstructured documents such as PDFs are turned into a graph: a large language model extracts the entities and the relationships between them from the text and converts them into RDF triples. In the second, tabular data is modeled as an ontology from its schema, keys and joins. Either way, the result is serialized to RDF in Turtle (.ttl), so the same downstream steps apply regardless of where the knowledge came from.

Loading it into SAP HANA Cloud is straightforward. You ingest the triples through the SPARQL_EXECUTE procedure, or stage the file in cloud storage and pull it in with IMPORT FROM RDF FILE from the Database Explorer. Once ingested, the graph is queryable with SPARQL, including from natural language, so business users can ask a question in plain words and get a grounded, relationship-aware answer.

The pipeline looks like this, from your source data on the left to a query-ready graph on the right. The labels are deliberately generic; your entities, documents and agent will be your own:

Build the graph once, then reuse it across pro-code agents and every Joule conversation.

The important idea for partners: you model the graph once. The same semantic asset can then ground many agents and many conversations, rather than being rebuilt for each use case.

Step 2: Bring your agent into Joule with A2A

Joule acts as the central orchestrator and entry point. When a user makes a request, Joule’s planning and reasoning engine decides how to fulfil it, which can include delegating the task to a custom agent. SAP supports two integration patterns, and the right one depends on how the agent was built.

For low-code agents built with Joule Studio, integration is largely automatic. Deploying the agent generates the required Joule artifacts, including a Joule Scenario and a Dialog Function, and registers the scenario in Joule’s Scenario Catalog. There is no endpoint or protocol to manage by hand.

For pro-code agents, the “Bring Your Own Agent” (BYOA) pattern uses the open A2A protocol, so you can build with any framework that speaks A2A. The flow is clean and decoupled:

Expose your agent as an A2A server with an HTTP endpoint that follows the A2A specification.
Create a Joule Scenario for the agent, and add a Dialog Function with an action of type agent-request.
Point that Dialog Function at your agent’s A2A endpoint.

At runtime, Joule becomes the A2A client. It prepares a request using the message/send method (A2A version 0.3.0), sends the user’s utterance to your agent, waits for the response, and presents the result. Joule handles synchronous replies within a 60 second window; for longer work, the agent uses push notifications to a Joule webhook, and context and task IDs carry state across multi-turn conversations. Secure communication is established through an Identity Authentication Service (IAS) App2App trust relationship between Joule and your agent.

One practical note worth setting expectations on: the Agent Gateway is not yet generally available, so today the architecture supports unidirectional, outbound communication from Joule to the agent. The bidirectional building blocks are expected to follow.

Two building blocks today, one coherent example soon

It is worth being clear about where things stand. Today these are two separate reference assets, not one finished scenario. The Knowledge Graph samples show how to build and query a graph from your documents or tables. The pro-code agent reference, btp-joule-a2a-pro-code-agent, shows the other half: a production-grade agent that plugs into Joule over A2A.

That reference agent is written in TypeScript on CAP, uses LangGraph for its logic, reaches foundation models through the SAP Cloud SDK for AI and Generative AI Hub, and demonstrates the full A2A round trip with Joule, including human-in-the-loop and webhook-based asynchronous updates, with Terraform for the BAIP setup. A companion community walkthrough by Felix Bartler shows the minimal version of the same A2A wiring.

The target pattern joins the two halves: a pro-code agent that treats your HANA Cloud Knowledge Graph as a tool, issuing SPARQL queries to fetch precise, relationship-aware facts, then reasoning with Generative AI Hub before returning a grounded answer through Joule. The graph supplies the trustworthy facts; the model supplies the reasoning; A2A supplies the delivery.

What this unlocks for SAP partners

This is where the partner opportunity is clearest. The pattern lets you help your customers bring their own domain data, knowledge and ontology into SAP, where it becomes a governed, reusable Knowledge Graph that grounds Joule. Instead of standing up a separate AI stack, your customers leverage the SAP platform investments they already have, including SAP HANA Cloud, SAP Business AI Platform (BAIP), Generative AI Hub and Joule, while you supply the domain expertise and the agent on top. Their proprietary knowledge stays in their SAP landscape, under their governance.

The advantages compound. The Knowledge Graph is a reusable asset that encodes domain expertise once and grounds every agent that uses it, which reduces hallucination and makes answers defensible. A2A is an open standard, so you keep framework freedom and avoid lock-in while still landing natively inside the SAP experience. And because the intelligence surfaces through Joule, adoption is frictionless: customers’ users get specialized answers in the assistant they already trust.

The build path is incremental. Start by turning one high-value slice of a customer’s knowledge, a set of documents or a key data model, into an ontology and Knowledge Graph in SAP HANA Cloud. Wrap a pro-code agent around it that queries the graph and reasons with Generative AI Hub. Then expose the agent over A2A and register it as a Joule Scenario. Each step is independently useful, and together they turn generic AI into your customer’s AI.

Further resources to get you started

Building Intelligent Data Applications with SAP HANA Cloud Knowledge Graphs: https://discovery-center.cloud.sap/protected/index.html#/missiondetail/4568/4856/
Knowledge Graph samples (documents and tables to ontology, 7 scenarios): github.com/IDGCOENA/saphanacloudkge
A2A pro-code agent reference implementation: github.com/SAP-samples/btp-joule-a2a-pro-code-agent
SAP Architecture Center, Integrating AI Agents with Joule: architecture.learning.sap.com
Community walkthrough, Connect Code Based Agents into Joule: community.sap.com
A2A protocol specification: a2a-protocol.org

Coming next - Stay tuned!

Coming next. We are building a coherent, end-to-end example that connects a custom Knowledge Graph to a Joule agent over A2A, and we are preparing a hands-on workshop to walk partners through it.

Share your use cases and questions in the comments. Don't hesitate to reach out as well in case you want some more close support.

Stop Tuning Your Database Manually - Let SAP HANA Cloud's Intelligent Advisors Do It

2026-07-02T13:05:27.997000+02:00

Managing a production SAP HANA Cloud database means constantly juggling performance, cost, and complexity. Tables grow beyond limits. Indexes drift out of sync with query patterns. Workload peaks spike memory and compute. Knowing what to change - and when - has traditionally required deep expertise and hours of manual analysis.

That's changing. SAP HANA Cloud delivers a suite of built-in functional advisors that analyze your instance and surface specific, actionable recommendations - directly from SAP HANA Cloud Central.

What Are the Functional Advisors?

The advisors are specialized analysis engines embedded in SAP HANA Cloud Central, accessible through the Recommendations card on any instance's Overview page. Each advisor monitors a specific domain - physical design, storage tiering, compute scaling, instance sizing - and produces recommendations with ready-to-apply actions.

Partition Advisor

The problem it solves

SAP HANA Cloud has a hard limit of 2 billion records per table. Large, unpartitioned tables also cause slow scans, data skew, and expensive delta merges. Knowing how to partition - which method, which key, how many partitions - requires deep knowledge of your data's shape and access patterns.

What the advisor does

It examines table specifications, row counts, query access patterns, and column cardinality, then applies a rule set that covers full-table limits, full-partition limits, frequent query predicates, temporal access patterns, and dynamic partition overflow. For each table it produces a single consolidated SQL recommendation with an importance level (High, Medium, or Low) so you know where to act first.

Key benefits

Proactively flags tables approaching the 2 billion record limit before they cause operational incidents
Recommends the right partitioning method (HASH, RANGE, Round-Robin, multi-level) based on actual data - not assumptions
Reduces the cost and risk of repartitioning large tables by getting the design right earlier
Works particularly well for very large tables, slow scan scenarios, data skew problems, and growing data volumes

Getting started

Enable the Partition Advisor from the Advisors tab. Provide credentials for a dedicated technical database user (not DBADMIN) with CATALOG READ and PARTITION ADMIN privileges. Default thresholds apply out of the box, but you can tune MIN_ROWS_FOR_PARTITIONING, REPARTITIONING_THRESHOLD, and INITIAL_PARTITIONS to match your operational standards.

Index Advisor

The problem it solves

Indexes that matched your query patterns six months ago may be dead weight today. Missing indexes leave performance on the table. Building the right index coverage manually means correlating workload statistics with table structures - a time-consuming process that rarely happens on any schedule.

What the advisor does

It analyzes all tables, existing index definitions, and workload statistics to identify two types of opportunities:

Create index — where adding an index on a specific column is expected to improve query performance based on observed access patterns
Drop index — where an index is rarely used or provides limited benefit, reducing storage and maintenance overhead

Each recommendation comes with a ready-to-execute SQL statement, so implementation is a copy-paste away.

Key benefits

Turns workload statistics into concrete index changes without requiring manual query analysis
Reduces both performance gaps (missing indexes) and unnecessary overhead (unused indexes)
Eliminates the guesswork of index selection by grounding recommendations in actual query behavior

Getting started

Enable from the Advisors tab. Requires CATALOG READ and the relevant INDEX privileges on the target schemas or tables.

Note: The current version supports filter queries on single tables. Join query support is on the roadmap.

NSE (Native Storage Extension) Advisor

The problem it solves

In-memory storage is SAP HANA Cloud's greatest performance asset - and its most expensive one. Not all data deserves to live in memory. Large, infrequently accessed tables or partitions silently inflate your memory footprint and cost, while small, hot objects may sit on disk unnecessarily.

What the advisor does

It collects access statistics over a configurable window (up to 90 days) and calculates scan density per object - tables, partitions, and columns - to determine data "temperature." Based on configurable thresholds, it generates two types of recommendations:

Cost recommendations: Move an object to page-loadable (disk) storage to reduce memory consumption
Performance recommendations: Move an object to column-loadable (memory) storage to improve response times

Each recommendation includes a confidence score reflecting how representative the observed workload window is.

Key benefits

Reduces in-memory footprint without degrading performance for hot data
Surfaces cost savings opportunities that are invisible without systematic access pattern analysis
Confidence scores let you prioritize high-certainty recommendations and defer uncertain ones
Supports bulk operations so you can apply changes incrementally and at scale

Getting started

Click NSE Advisor in Recommendation Card and enable the NSE Advisor in NSE Recommendations tab. Configure your collection window, hot/cold object percentage targets, and minimum object size thresholds. Requires TABLE ADMIN, PARTITION ADMIN, and CATALOG READ system privileges.

ECN (Elastic Compute Node) Advisor

The problem it solves

Some workloads are predictably periodic - end-of-month reporting, nightly batch jobs, seasonal peaks. Provisioning a coordinator large enough to handle the peak means over-paying for compute during the other 90% of the time. But manually identifying which queries to route, when to spin up an ECN, and when to tear it down is operationally complex.

What the advisor does

It analyzes past coordinator workload against configurable memory and compute thresholds to identify peak windows where query routing to a temporary elastic compute node would bring the coordinator back within threshold. The resulting recommendation specifies the ECN size (memory and compute), the workload classes to route, and a provisioning/de-provisioning schedule.

You can apply the recommendation in two ways:

ECN Policy (recommended): Creates an automated policy that provisions and de-provisions ECNs on your behalf - either on a fixed schedule (daily, weekly, monthly) or dynamically in response to live system load. The policy manages workload class routing automatically.
Manual: Add the ECN via Manage Configuration, update workload class routing locations, and remove the ECN when the time range ends.

Key benefits

Eliminates the need to maintain an oversized coordinator for occasional peaks
Right-sizing the coordinator for regular workload after implementing ECN routing can meaningfully reduce total cost of ownership
ECN Policies fully automate the provisioning lifecycle, removing operational overhead

Getting started

The ECN Advisor requires at least 5 vCPUs and at least one existing workload class. Enable from the Advisors tab, set memory and compute thresholds, define an analysis timeframe (30 minutes to 24 hours), and generate a recommendation. Enabling expensive statement tracing during the analysis window improves recommendation accuracy.

Performance Class Advisor

The problem it solves

Knowing when your instance needs to be resized - and to which performance class - is rarely obvious until performance has already degraded. Reactive resizing means business continuity risk. Proactive resizing based on gut feel means unnecessary cost.

What the advisor does

It runs automatically every Sunday, analyzing 2, 4, or 6 weeks of historical compute and memory utilization to determine whether your current performance class and instance size are still appropriate. When it identifies a mismatch, it produces a specific recommendation - which performance class and size to move to, and why.

Key benefits

Automatically generated - switch it on once, and it runs weekly without any manual trigger
Grounds sizing decisions in actual historical workload rather than estimates or guesswork
Proactively surfaces the need to upsize before performance degradation reaches users

Getting started

Enable from the Advisors tab and choose your analysis window (2, 4, or 6 weeks). No additional configuration required.

Note: The current version supports up-sizing scenarios only. Down-sizing recommendations are on the roadmap.

Getting Started with All Advisors

All advisors are accessible from the Recommendations card on any instance's Overview page in SAP HANA Cloud Central:

Open your instance's Overview page
Select the Recommendations card
Go to the Advisors tab (*NSE Advisor is located in NSE App as of today. It will be fully integrated into Recommendation App soon)
Select any advisor row to view details, enable it, and configure thresholds

You'll need the SAP HANA Cloud Administrator role collection to enable and configure advisors, and SAP HANA Cloud Viewer to read recommendations.

What's Coming — Analytics Advisor (Q3 2026)

The advisor portfolio is actively expanding. Analytics Advisor will analyze OLAP query performance across your instance, identify slow calculation views, and recommend creating MDS cubes - materialized aggregation structures that dramatically reduce response times for repeated queries.

Database sizing, physical design, storage tiering, and compute management are all moving from reactive, expert-driven tasks to automated, data-driven operations. Each new advisor is a step toward a database that tunes itself.

What’s New in SAP HANA Cloud – July 2026

2026-07-03T11:29:14.472000+02:00

The Q2 2026 release of SAP HANA Cloud continues to advance our vision of delivering an intelligent, AI-native, and enterprise-scale data platform. This quarter introduces innovations that make it easier to build AI-powered applications, manage large-scale enterprise workloads, simplify database administration, and strengthen security across your data landscape.

From deeper integration with SAP AI Core and new machine learning capabilities, to larger database instance sizes, enhanced data integration, and intelligent administration tools, this release allows you to unlock greater value from your data while reducing operational complexity.

Whether you're building next-generation AI applications, modernizing your enterprise data landscape, or optimizing business-critical workloads, SAP HANA Cloud continues to provide the foundation for secure, scalable, and intelligent data management.

Let's take a look at some of the key innovations introduced with the Q2 2026 release.

Agentic Data Access in SAP HANA Cloud

We're taking another major step toward an AI-native data platform with new capabilities that enable agentic data access in SAP HANA Cloud.

At the core of this innovation is the ability to automatically generate a custom database objects knowledge graph. SAP HANA Cloud scans your database metadata including: tables, views, columns, and their relationships, and automatically builds a semantic representation of your data landscape.

By eliminating the need for manual semantic modeling, this knowledge graph provides a rich foundation for data discovery, reasoning, and AI-driven interactions. It enables both users and AI agents to better understand how enterprise data is organized and connected.

Building on this semantic foundation, we are introducing the Database Object Discovery Tool and the Data Retrieval Tool, available beginning in early July.

Today, working with enterprise data often requires you to understand complex database schemas, identify the right database objects, and manually write SQL queries to retrieve information. With these new capabilities, you can simply describe what they are looking for using natural language.

The Database Object Discovery Tool identifies the relevant database objects and relationships by leveraging the database objects knowledge graph. The Data Retrieval Tool then translates your request into an executable SQL statement and runs it directly within SAP HANA Cloud.

Together, these capabilities dramatically simplify the way we can discover, understand, and query enterprise data, without requiring deep SQL expertise or detailed knowledge of the underlying database schema.

Built on the multi-model foundation and Knowledge Graph Engine of SAP HANA Cloud, these innovations lay the groundwork for a new generation of conversational, agent-driven, and AI-powered data experiences, making it easier than ever to build intelligent applications on enterprise data.

To learn more about the agentic database tools, take a look at Shabana's blog post.

You can also learn how to set them up through this tutorial by @Dan_vL

Natural Language Processing (NLP), Machine Learning and AI Core integration

With the Q2 2026 release of SAP HANA Cloud, we continue to strengthen embedded NLP and Machine Learning capabilities with broader SAP AI Core integration, unlocking access to SAP RPT-1 and LLMs and thus completely new type of AI-driven database applications.

Key highlights as part of the Predictive Analysis Library (PAL) include:

A new function for synthetic data generation using diffusion models, e.g for securing data privacy when training custom AI models
Time Series Forecasting function enhancements like support for lagged regressors with Additive Model Time Series Analysis (aka prophet) and easier time series cross validation using the Unified Time Series procedures for better forecast predictions
Further enhancements include columnar analysis of large data sets using Online Univariate Analysis

The full list of PAL enhancements for SAP HANA Cloud 2026 Q2 is documented here. Additionally, the python Machine Learning client for SAP HANA 2.29 is supporting several new functions (see here) like PCA-based vector dimension reduction or the text tf-idf operator in AutoML.

Key highlights for SAP AI Core integration include:

Remote sources to SAP AI Core now supporting use of LLMs and SAP RPT-1 as standardized and secure gateway for 3rd party LLMs access
Benefit from on-the-fly predictions, without the need to create, train and manage use-case specific ML models by simply utilizing the new AI_TABULAR_PREDICTION SQL procedure to access tabular AI models like SAP RPT-1
Ability to leverage LLM capabilities, directly from the database SQL processing engine, by simply utilizing the new AI_TEXT_COMPLETION SQL function to execute one-shot-tasks like text generation or text summarization based on your text data managed in SAP HANA Cloud, unlocking for completely new type of LLM-driven application scenarios.

These enhancements focus on making tabular AI predictions using custom AI models or semantic data retrieval scenario easier to use and applied to real business application data.

Right-sizing your instance with Performance Class Advisor

Knowing whether your SAP HANA Cloud instance is the right size shouldn't require manual analysis or reactive firefighting. The Performance Class Advisor changes that by continuously monitoring your instance's compute and memory usage and automatically generating right-sizing recommendations every Sunday, without any manual trigger.

You choose a lookback window of 2, 4, or 6 weeks to match your workload patterns, and the advisor checks whether CPU or memory usage has exceeded 80% during that period, if either threshold is breached, a recommendation is triggered. The advisor then calculates the optimal upsized spec, targeting approximately 20% additional capacity and snapping to the nearest valid instance configuration.

In this initial release, recommendations are limited to upsizing only, as downsizing carries higher risk given that short lookback windows may not capture infrequent but critical workload spikes, and that is in our backlog to investigate further. The benefits are threefold: right-sizing guidance based on actual historical workload patterns rather than guesswork; proactive resource management that surfaces capacity pressure before it impacts business continuity, giving you time to act rather than react; and automated weekly insights with zero manual effort — switch it on once, and stay informed from there.

Learn more on SAP HANA Cloud's Intelligent Advisors in this blogpost by @jinheejeong

Automated SQL Plan Management with SQL Plan Advisor

SQL execution performance can fluctuate for various reasons. A common culprit is a change in the execution plan within the SQL Plan Cache, either because a cached plan becomes suboptimal over time, or because an inefficient plan was cached based on the initial parameter sets used during compilation.

To better manage these regressions, SQL Plan Advisor was introduced in QRC 2/2024. It automatically detects degraded query executions by analyzing historical performance statistics stored via SQL Plan Stability. To resolve a performance dip, older, historical plans had to be verified to ensure they performed faster than the currently cached plan. However, this verification and testing process could only be triggered manually.

With QRC 2/2026, this testing process is now fully automated. The system autonomously executes faster historical plans to verify their effectiveness, swapping out the degraded cached plan to seamlessly restore optimal database performance.

Please check out the details in the blog by @Taesuk found here.

Database Administration & Developer Productivity

Import & Export

SAP HANA Cloud Central will soon be adding a new top-level application named Import and Export designed to enable users to quickly complete import and export operations within SAP HANA Cloud. This application provides guided wizards for importing data into a table, exporting data from a table or view, and importing and exporting both catalog objects and SAP HANA deployment infrastructure containers. Supported storage providers include SAP HANA Cloud data lake, Amazon S3, Microsoft Azure storage, and Google Cloud storage. Users can also view the generated SQL for any import or export task directly within the wizard.

Additionally, the export wizard will support the ability to provide a query to further filter the data being exported.

SQL Console

Improved Tab Management
Previously if a SQL console tab was closed accidently, its contents were gone. Users can now restore closed tabs using the Restore Last Closed Tab option in the toolbar. Additionally, tabs can be renamed and reordered, making it easier to stay organized when working across multiple queries at once.

A new search capability is also available from the actions menu, that lets users search across the content of all open tabs enabling a specific query to be quickly located.

Enhanced Syntax Help Panel
The syntax help panel has also received a refresh. Object details are now collapsible, reducing visual clutter when users only need a quick reference. Columns and parameters are also searchable, which allows users to find what they need without scrolling through extensive lists. These columns are now clickable as well – selecting one directly inserts it into the editor.

SQL Results
Users now also have more control within SQL results, which has been enhanced with options to handle how data is displayed and refreshed. Users can customize which columns they want to be shown or hidden and also reorder them in whichever way that suits their workflow. Results can also be re-executed on demand without requiring parameters to be re-entered.

Data Integration (Federation & Replication)

SQL on Files: Apache Iceberg REST Catalog support in SAP HANA Cloud

Direct read-only access to Apache Iceberg tables in object storage, which has been introduced since QRC 3/2025, has offered real-time analytics on Iceberg lakehouses without moving data into SAP HANA Cloud. With QRC 2/2026, it evolves further by supporting Apache Iceberg REST Catalogs, which is how the modern enterprise lakehouses centralize table management, access control, and metadata governance.

Through the new icebergcatalog adapter, SAP HANA Cloud now connects directly to spec-compliant Iceberg REST Catalogs across AWS, Azure, and GCP, bringing enterprise-grade integration to your Iceberg lakehouse with minimal effort. Note that while the adapter is designed to work with any spec-compliant Iceberg REST Catalog, only a defined set of providers is officially certified by SAP per QRC.

To learn more about SAP HANA Cloud's new Apache Iceberg REST Catalog support, take a look at @SeungjoonLee's blog post here.

S/4HANA CDS View Entity replication to SAP HANA Cloud

S/4HANA Federated access was introduced in QRC 1/2024, as detailed in the blog Taking Data Federation to the Next Level: Accessing Remote ABAP CDS View Entities in SAP HANA Cloud. Building on this, QRC 2/2026 introduces support for replicating data directly to SAP HANA Cloud.

CDS view replication allows you to copy data from SAP S/4HANA CDS view entities into local tables within SAP HANA Cloud, enabling fast local analytics without the need for remote federated queries.

Key benefits include:

Lower Latency: Data resides locally, and efficiency is maximized by replicating only changed rows.
Reduced Source Overhead: Impact on the source system is minimized because replication can be scheduled at custom intervals or run entirely on demand.
Flexible Filtering: Data can be filtered by specific rows, selected columns, or both.

You can configure replication via SQL or by using the Data Replication tool in SAP HANA Cloud Central.

To learn more about SAP HANA Cloud’s new S/4HANA CDS View replication, check out @Taesuk ’s blog post here.

Security, Data Protection & Privacy

Post-quantum cryptography (PQC) for Transport Layer Security (TLS) connections

With the Q2 2026 release, SAP HANA Cloud database introduces post-quantum cryptography (PQC) for TLS connections, providing quantum-resistant protection for all data in transit between clients and SAP HANA Cloud databases.

Post-quantum cryptography addresses the "harvest now, decrypt later" threat — where adversaries capture encrypted traffic today with the intent of decrypting it once quantum computers become capable. By enabling PQC now, SAP HANA Cloud ensures that data encrypted today remains protected against future quantum attacks.

Key capabilities include:

Hybrid Post-Quantum Key Exchange

A transparent ML-KEM key establishment negotiated during TLS 1.3 handshakes, combining classical and quantum-resistant algorithms. Enabled by default for all SAP HANA Cloud databases with no customer configuration required.

Full Backward Compatibility

Clients with PQC support (SAP Client using OpenSSL 3.5+, SAP HANA client 2.29+) automatically negotiate the quantum-resistant hybrid exchange. Clients without PQC support safely fall back to classical key exchange with zero disruption to existing applications.

Built-in Observability

New SSL_KEY_EXCHANGE and SSL_SIGNATURE columns in M_CONNECTIONS and M_OUTBOUND_NETWORK_IO system views, enabling administrators to verify PQC adoption per connection and identify clients that need upgrading.

The feature is aligned with NIST post-quantum standards (ML-KEM / FIPS 203) ahead of anticipated regulatory mandates and requires no customer action to activate.

Typical use cases include verifying quantum-safe connection status across the landscape and meeting compliance requirements for post-quantum readiness.

Access Logging & Column-Level Security for SQL Views

SAP HANA Cloud introduces two complementary capabilities for protecting sensitive data: access logging for columns containing sensitive data and column-level security for SQL views. Together, these address two sides of the compliance equation - preventing unauthorized access and detecting all access for audit purposes - enabling compliant direct SQL access to data containing sensitive columns.

The Context

Regulations like GDPR require both prevention of unauthorized access to personal data AND demonstrable accountability for all access. Direct SQL access to HANA databases containing sensitive data requires enforcement and audit trails to meet these compliance requirements.

These two capabilities address this:

Prevent:	Column-Level Security for SQL Views	Ensures unauthorized users cannot see sensitive columns (returned as NULL)
Detect:	Access Logging for Sensitive Columns	Logs who accessed which sensitive columns, when, and on which table (values never logged)

Access Logging

Access logging is activated directly in the table definition using the AUDIT (READ | NONE) syntax. Once columns are marked, read access is automatically reported via the predefined "SAP - column access" audit policy, as no custom policy creation is needed. Both direct and indirect access is reported, including access via views or during procedure execution. The audit log entry includes the schema name, table name, and the list of accessed columns (quoted and comma-separated), while the actual data values and SQL statements are never logged - ensuring the audit trail provides accountability without creating a secondary repository of sensitive data.

Column-Level Security

Column-level security for SQL views provides a dynamic access control mechanism. Columns on SQL views are tagged with DPP classification identifying Sensitive Personal Data, and the authorization model determines which tagged columns are permitted for access. At query execution time, the engine evaluates authorization dynamically – this evaluation is not tied to the current database user but can rely on any information in the session context or other tables. Authorized columns return actual values, while unauthorized columns return NULL. The key design decision is that columns are masked, not omitted - query structure remains stable for all consumers, meaning downstream dashboards, pipelines, and applications continue to function without modification.

Combined Value

Together, these capabilities enable compliant direct SQL access to sensitive data in SAP HANA Cloud. Column-level security ensures users see only data they are authorized to access, while access logging provides auditable evidence of all access events, satisfying both the prevention and accountability requirements of GDPR and similar regulations.
The operational overhead is minimal: DDL-based activation for access logging, a system-managed audit policy, and dynamic authorization evaluation for column-level security - with no duplicate views, no application-layer workarounds, and no custom configuration frameworks required.

Increase in-memory capacity with up to 16 TB and 24 TB Instances on AWS

As enterprise workloads continue to grow in size and complexity, organizations increasingly require larger in-memory database configurations to support mission-critical transactional and analytical applications.
With the Q2 2026 release, SAP HANA Cloud expands its scalability by introducing support for 16 TB and 24 TB database instances on AWS.

These new instance sizes are designed for customers running some of the most demanding enterprise workloads, providing the processing power and memory capacity required for large-scale SAP and custom applications while maintaining the simplicity of a fully managed cloud service.

To ensure predictable performance and guaranteed resource availability, these instances are deployed on dedicated, pre-reserved physical infrastructure that is allocated exclusively to a customer's subaccount within a selected AWS availability zone. The reserved capacity remains available throughout the three-year reservation period, regardless of whether the database instance is running, stopped, paused, or temporarily deprovisioned.

Customers can request these instance sizes directly through SAP HANA Cloud Central by opening an SAP support ticket. Once the requested capacity has been approved and the dedicated infrastructure has been provisioned, the new database instance can be deployed against the reserved resources.

Support for 16 TB and 24 TB instances is currently available in selected AWS regions. For the latest information on supported regions and availability zones, please refer to the SAP HANA Cloud documentation.

Data Lake Innovations

Thin Clone Decoupling for Data Lake Relational Engine

Building on the thin clone capability in SAP HANA Cloud, data lake relational engine, which is designed for creation and deployment of clones of petabyte-scale databases in development and testing environments in just a few minutes, we are introducing thin clone decoupling. Thin clone decoupling promotes a thin clone to a fully standalone SAP HANA Cloud, data lake relational engine instance. Once the decoupling process completes, the instance operates independently, completely detached from the parent instance.

Upon decoupling, backups are enabled on the decoupled instance, making it eligible for disaster recovery scenarios. The decoupled instance can itself serve as a source for creating new thin clones.

 Thin clone decoupling opens a clear path for promoting development or test databases to production-grade instances improving data reliability and integrity.

Innovations on Calculation View features

The calculation view features blog for 2026 QRC2 by @jan_zwickel covers several new calculation view capabilities. Two complementary deployment options help to reduce deployment time and protect privileges: optimized redeployment skips unchanged dependent views instead of dropping and recreating them all, and the new replace option performs in-place replacement so that cross-container privileges are not lost.

On the scalability front, Active/Active read-enabled hints can be set at the individual calculation view level for fine-grained query routing to read replicas. A Join-to-Non-Equi-Join conversion in the context menu eliminates the need to rebuild join logic from scratch when switching from equi joins to non-equi joins. The support of calculated measures executed at query runtime allow defining runtime calculations for MDS Cubes in calculation views. Finally, a new status dialog surfaces the view's connection state, read-only reasons, data classification inconsistencies, and BDC integration status when a calculation view is opened.

Thanks for taking the time to explore the What’s New in SAP HANA Cloud on Q2 2026 innovations!

If you’d like to go deeper into the technical details of the Q2 2026 release, we recommend visiting the What’s New Viewer in the technical documentation. It provides a comprehensive overview of the full release scope. To stay informed about upcoming innovations, announcements, and best practices, follow the SAP HANA Cloud tag.

You can also find our latest blog posts by searching for the #whatsnewinsaphanacloud hashtag.

If you missed earlier What’s New webinars, you’ll find recordings of past sessions and upcoming events in our YouTube playlist. Our What’s New webinar covering the Q2 2026 innovations will be posted on this playlist very soon. You can also download the slides from the webinar here.

Do you have questions about SAP HANA Cloud or want to share your thoughts on the new features?
Join the conversation in the SAP HANA Cloud Community Q&A or leave a comment below. We’d love to hear from you!

Knowledge Graph Agent on SAP HANA Cloud Series – Part 1: Why Knowledge Graph for SAP Data

2026-07-04T15:44:34.848000+02:00

This blog is part of a blog series on building AI Agents with SAP BDC (Business Data Cloud) Data Products and SAP HANA Cloud Knowledge Graph Engine:

Knowledge Graph Agent on SAP HANA Cloud Series – Part 1: Why Knowledge Graph for SAP Data
Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-1: Ontology Standards and Concepts
Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-2: Designing the Ontology for SAP Data
Knowledge Graph Agent on SAP HANA Cloud Series – Part 3: Data Pipeline from BDC to HANA Cloud KGE
Knowledge Graph Agent on SAP HANA Cloud Series – Part 4: Building an Agent with SPARQL and SQL
Knowledge Graph Agent on SAP HANA Cloud Series – Part 5: Lessons Learned

Enterprise systems are vast, with thousands of tables, hundreds of business processes, and countless APIs, all interconnected in ways only domain experts fully grasp. For AI Agents to be genuinely useful in this environment, they need to understand not just what the data is, but how it all connects: which Product belongs to which Sales Order, which WorkCenter is located in which Plant, which Supplier serves which material. This understanding does not come from the data itself. It needs a dedicated semantic layer that makes business meaning explicit and machine-readable. Knowledge Graphs provide exactly that layer. SAP HANA Cloud now offers a native Knowledge Graph Engine to build it on top of SAP BDC Data Products. This series walks through the full journey: from why this layer matters, to how to design and build it, to how an AI Agent uses it to answer real business questions.

In this post, we describe why a Knowledge Graph is the right semantic foundation for AI Agents querying SAP business data, and how SAP BDC Data Products combined with HANA Cloud Knowledge Graph Engine make this practical.

Table of contents:

Introduction
Why Knowledge Graph now
The problem: enterprise questions are not single-table
Vector RAG and Knowledge Graph: different strengths
What a Knowledge Graph solves: relationships made explicit
Why SAP BDC Data Products
One Domain Model: an extensible vocabulary foundation
The division of labor: KG and SQL
The full journey: from Competency Question to AI Agent

1. Introduction

Knowledge Graphs have a steep learning curve. Ontology, Triple Store, SPARQL, RDF, OWL, and SHACL introduce a large amount of unfamiliar terminology that can be overwhelming at first. Anyone comfortable with relational databases and SQL is likely to ask "How is this different from a SQL JOIN?" early on, and to question whether KG is necessary when Vector RAG is already available.

The good news is that the field already has well-organized foundational material:

Stanford's Ontology Development 101 is the standard introduction to ontology design, structured as a seven-step methodology.
The W3C Direct Mapping and R2RML recommendations define precise rules for translating relational data into RDF.
SHACL is the W3C standard for validating graph data integrity, and OWL provides the standard vocabulary for inference rules.

The challenge is that these resources are scattered. Each is authoritative within its own scope, but none of them answers the practical question: "To build an AI Agent on enterprise data, in what order should these pieces be combined, and how?" That question can only be answered by building.

What this series aims to do

This series weaves those scattered standards together with SAP's strengths into a single narrative. While building an AI Agent on top of SAP BDC Data Products with the HANA Cloud Knowledge Graph Engine, we documented how the theory applies to real SAP data and where the standards stop short and require domain decisions.

For anyone heading down a similar path, this series should serve as a useful starting framework. With the standards already established by others as a foundation, you can focus on the SAP domain decisions that actually matter.

💡A note on the workflow.
In production, ontology design and long-term maintenance should rely on modeling and governance tools such as Protégé or Metaphactory. This series uses AI-assisted Vibe Coding as a pragmatic way to create a first draft quickly, especially for scenario-based projects, and to learn the domain decisions that must later be reviewed and refined in dedicated modeling tools.

How to follow along

The actual production data cannot be shared publicly. However, all code and project structure used throughout this series is available in the GitHub repo below. No sample data is included, but you can use the same structure and code as a reference to apply the approach in your own SAP environment or a different domain.

📁 github.com/claudiopark86/sap-bdc-kge-agent-workshop

The final output this series builds, a KG-powered AI Agent for supply chain risk analysis, can be seen in action here before you begin:

2. Why Knowledge Graph Now

Building useful AI Agents has made one thing clearer than ever: context matters.

An Agent answering a user question needs to know where to look and what is connected to what. Enterprise systems contain a vast number of business processes and data attributes, all entangled. An AI Agent needs to understand this landscape and produce accurate answers for mission-critical work running on top of it.

Can all of this context be injected through the prompt? The scale is too large. Embedding every table, every relationship, and every business rule into a prompt is not realistic, and even if it were, there is no guarantee that the LLM would retrieve the right pieces from such a payload.

What about vector similarity search? Vector RAG is strong at finding "similar documents," but it has limitations when it comes to structural relationship traversal including questions like "Which materials does this supplier provide, which finished goods do those materials feed into via the BOM, and which customers buy those finished goods?" Similarity finds semantic neighbors; it does not follow an explicit relationship chain.

A Knowledge Graph addresses both limitations from a different angle. Relationships are stored explicitly in the database, and the AI traverses that structure whenever it is needed. There is no need to push everything into the prompt, and no need to guess by similarity. The exact connections live on the graph.

3. The Problem: Enterprise Questions Are Not Single-Table

A supply chain manager asks a question like this:

"If WorkCenter Z_ASM3 goes down for maintenance, which customers are affected in delivery, and how large is the revenue exposure?"

It sounds like a SQL question at first glance. But answering it requires traversing a chain that spans multiple domains:

No single table contains this entire chain. It can be expressed with JOINs, but doing so requires knowing the schema, the join keys, and which tables to include in advance. An AI Agent that receives a natural language question must discover this path dynamically.

This question is both the starting point and the destination of the series

The question above is not just a demo scenario. It is a Competency Question (CQ), the concept Stanford's Ontology Development 101 identifies as the starting point of KG design. Before any modeling begins, you write down "What business questions should this KG answer?"

💡 The CQ runs through the entire series, from start to finish.
A Knowledge Graph cannot be built all at once. The domain is too broad, the data is too large, and the boundaries of "where to stop" are unclear. This is why Ontology Development 101 recommends starting from the questions the KG must answer.
The CQ surfaces at three points in this series:
At the start (Part 2-1, 2-2): The CQ determines which classes and relationships are needed. Nouns in the question become classes; verbs become relationships. Rather than modeling every entity, we build only the minimum required to answer the question.
In the middle (Part 3): The CQ determines which relationships should be validated first and which data should be prioritized. All relationships matter, but the ones that must be alive first are the chain the CQ points to.
At the end (Part 4): The CQ becomes the quality benchmark for the KG. If the CQ produces an answer, the KG is working as intended. If it does not, the gap is visible. The CQ effectively becomes the SPARQL test case.
The same question works twice: first as a design specification, then as a quality benchmark. This is also why a KG is rarely complete in a single pass: every new CQ triggers the same cycle again.

This is why the Z_ASM3 question keeps reappearing throughout the series. Part 2 determines which classes (WorkCenter, FinishedGood, …) and relationships (producesProduct, …) are required to answer it. Part 3 validates those relationships against real data. Part 4 confirms that the Agent actually answers the question through SPARQL and SQL. A single question forms the spine of the entire series.

And this is precisely the problem Knowledge Graph was designed for: storing a chain that no single table can hold, and traversing it dynamically.

4. Vector RAG and Knowledge Graph: Different Strengths

SAP's official Knowledge Graph introduction puts it this way:

"Vector databases help AI find things that are similar; Knowledge graphs help AI understand how things are connected."

The two are not competitors. They excel at different things. But when building an AI Agent on top of ERP data, this difference becomes decisive.

Three situations where Vector RAG struggles:

1. Questions that require relationship traversal

"Which finished goods does this part go into?" cannot be answered through similarity search. It requires following a structural connection: purchased material → BOM item → finished good. Text embeddings do not represent this connection.

2. Linking data across multiple systems

Consider combining S/4HANA procurement data with the World Bank's Logistics Performance Index (LPI) to ask, "Which purchase orders involve suppliers in countries with high logistics risk?" Vector RAG can surface similar passages within each document, but it does not explicitly link entities from different sources.

3. Precise condition handling

"Suppliers with a risk score below 20" is not a similarity question; it is a filter. Numeric conditions, aggregations, and ordering all require structured queries.

In summary: Vector RAG is strong at document search and semantic similarity. For traversing structural relationships in ERP data, one more layer is required. That layer is the Knowledge Graph.

5. What a Knowledge Graph Solves: Relationships Made Explicit

A Knowledge Graph stores data as nodes (entities) and edges (relationships):

bdc:WorkCenter_Z_ASM3  bdc:producesProduct  bdc:Product_MZ-FG-C900
bdc:WorkCenter_Z_ASM3  bdc:producesProduct  bdc:Product_MZ-FG-C950
bdc:WorkCenter_Z_ASM3  bdc:producesProduct  bdc:Product_MZ-FG-C990

bdc:WorkCenter_Z_ASM3  bdc:locatedAt  bdc:Plant_1010

This is not a table join. It is a structure where business-meaningful relationships are stored explicitly.

An AI Agent queries this structure with SPARQL:

SELECT ?product WHERE {
  bdc:WorkCenter_Z_ASM3 bdc:producesProduct ?product .
}

One line. No joins. A query that is understandable without prior schema knowledge.

When numbers are required, the Agent switches to SQL:

SELECT "SoldToParty", SUM("TotalNetAmount") AS revenue
FROM BDC_DP.SALES_ORDER_ITEM
WHERE "Material" IN ('MZ-FG-C900', 'MZ-FG-C950', 'MZ-FG-C990')
GROUP BY "SoldToParty";

The SPARQL query identifies three product IDs; SQL aggregates the revenue. The detailed SQL design is covered in a later post in this series. What matters here is the principle itself: the two queries divide the work between them.

This is the core principle of the Agent we built: the KG handles structural relationships, and SQL handles quantitative aggregation.

6. Why SAP BDC Data Products

We began Section 1 by noting that Knowledge Graphs generally have a steep learning curve. The good news is that SAP data makes KG development significantly more practical, thanks to SAP's One Domain Model.

Business entities such as SalesOrder, Customer, WorkCenter, and Supplier are already defined in a standardized vocabulary. When these are published as BDC Data Products into HANA Cloud, the CSN metadata is included as well. Half of ontology design, namely which entities exist and what to call them, is effectively solved before you start. There is no need to brainstorm entity names on a whiteboard.

The same starting point is available even without going through BDC, when working directly with S/4HANA ERP. CDS View definitions already declare entity names, field annotations, and associations using meaningful business vocabulary. The raw material for an ontology draft is already inside the system. BDC surfaces this as curated Data Products, but teams working directly with S/4HANA can take advantage of the same strength.

LLMs already know this vocabulary. ABAP table names such as EKKO or KNA1 are essentially opaque strings to an LLM, whereas SalesOrder and Customer appear millions of times in training data. The moment your KG and your LLM share the same vocabulary, writing SPARQL becomes far easier for the Agent.

That said, the original ABAP table names still live inside the SAP system. The question is how SAP BDC Data Products replace that vocabulary with business terminology.

What happens when you connect directly to S/4HANA tables

Consider some core S/4HANA table names:

Table	Meaning
`EKKO`	Purchase Order Header
`EKPO`	Purchase Order Item
`MARA`	Material Master
`KNA1`	Customer
`CRHD`	Work Center Header

These names have lived in SAP systems since the ABAP era. For experienced SAP users, they are immediately recognizable. But the names themselves do not convey their meaning intuitively. A four- or five-letter abbreviation typically requires separate learning or documentation lookup to map to a business concept.

The same applies to LLMs. An LLM that has encountered these abbreviations frequently in SAP contexts may recognize some of them, but not as reliably as business vocabulary like SalesOrder, which appears millions of times in training data. When building an Agent, a significant share of prompt engineering ends up teaching the LLM that "EKKO is the purchase order header," and even then, hallucinations still occur.

SAP BDC Data Products solve this problem at the source.

What a BDC Data Product provides

SAP Business Data Cloud (BDC) exposes S/4HANA data as curated Data Products. Each Data Product:

Has a clear name: SalesOrder, Customer, WorkCenter, Product
Has a CSN (Core Schema Notation) schema: including field names, semantic annotations, and FK associations
Is published as a HANA Cloud Virtual Table: HANA Cloud accesses data in BDC data products through a Virtual Table interface, with no ETL pipeline on your side
Is discoverable through the BDC catalog

The actual flow for bringing a Data Product from BDC into HANA Cloud:

BDC Catalog & Marketplace → Data Products tab
Select a Data Product → Add Target → Choose HANA Cloud → Share
HANA Cloud Central → Data Product tab → Install

That is the entire process. There are no complex ETL pipelines. For detailed instructions, please check out this SAP tutorial.

After installing the data product, you can also download CSN definitions of it as the screenshot below.

The CSN files, downloaded at this stage, will be used in the Part 2-2 of this blog series.

Virtual Table: real-time access without replication

SAP BDC replicates and curates data from S/4HANA and exposes it as HANA Cloud Virtual Tables. A Virtual Table is not a local copy you manage. BDC handles the data movement from S/4HANA, and HANA Cloud accesses it through the Virtual Table interface. There is no additional ETL pipeline on your side.

For an AI Agent, this has two implications:

When generating KG instances, you query the Virtual Table, which reflects BDC's current view of the S/4HANA data.
The Agent's SQL queries run against the same data in data products.

The trade-off is latency. Cross-system queries are slower than local ones. This is why we place stable, smaller master data into the KG while handling transactional data through Virtual Table SQL, where data freshness matters more than raw speed.

7. One Domain Model: An Extensible Vocabulary Foundation

BDC Data Products are not simply a name-translation layer. They are built on top of SAP's One Domain Model (ODM). ODM defines business entities in a unified way across SAP products, providing a standard vocabulary at the data model level, Customer, Product, Supplier, WorkCenter. Because the type name itself carries business meaning, the same business concept is identified by the same vocabulary across multiple SAP applications.

The greatest value this standard provides to a KG is extensibility.

1. When adding other SAP products to the KG. Suppose you begin by building a KG with S/4HANA supply chain data. Later, you want to incorporate data from another SAP product into the same KG. If the vocabulary differed across systems, you would need to construct and maintain mapping tables every time. On top of ODM, the starting vocabulary is already shared, so adding a new system incrementally becomes significantly simpler.

2. When other teams reuse the same KG. Because ODM vocabulary is consistent across SAP, KG reuse across teams is straightforward. When another team adds entities from its own domain to an existing KG, the vocabulary and structure do not collide.

3. KG and LLM share the same vocabulary. As a side effect, ODM vocabulary (Customer, Supplier, WorkCenter) is well-represented in LLM training data, so LLMs recognize it reliably. The KG classes we built also use this vocabulary, such as bdc:WorkCenter, bdc:Supplier. Natural language question → SPARQL → KG result all flow on the same vocabulary.

One Domain Model turns a KG from "a model you build once and are done with" into "an asset you can continue to extend and connect."

📖 Reference: SAP Community, "Harnessing Half a Century of Knowledge: SAP's Journey of Enriching APIs with Metadata"

8. The Division of Labor: KG and SQL

The architecture we chose rests on a single principle.

The KG handles structural relationships. SQL handles quantitative aggregation.

Role	Technology	Target Data	*Question Type*
Relationship traversal	SPARQL over HANA KGE	Master data (WorkCenter, Product, Supplier, Plant)	"What does Z_ASM3 produce?"
Numeric aggregation	SQL over HANA Virtual Table	Transactional data (SalesOrder, PurchaseOrder, BillingDocument)	"How much revenue do those products represent?"

SAP BDC Data Products combined with HANA Cloud KGE realize this division of labor on a single database. SPARQL and SQL run on the same HANA instance, and merging their results is handled by the database engine rather than the LLM (we cover this in detail in Part 4 Section 2 with SPARQL_TABLE).

If this principle holds, the next question is how to actually build it.

9. The Full Journey: From Competency Question to AI Agent

[0] The Competency Question is both the starting point and the validation benchmark for every step. The "CQ runs through the series from start to finish" point emphasized in Section 2 appears directly at positions 0 and 4 of this diagram. The CQ determines which classes and relationships are needed at [2-1] Ontology design, and serves as the test case for whether the KG actually answers the question at [4] Validation. The same question works twice.

KG creation has two parts:

Ontology (schema): What classes and relationships exist. It is created once and rarely changed. Definitions like bdc:WorkCenter and bdc:producesProduct belong here.
Instance (data): Actual WorkCenters, Products, and Suppliers. It is regenerated when data changes. The Virtual Tables are read, and TTL files are produced for the actual entities of the classes declared in the ontology.

By analogy: the Ontology is the "blueprint," and the Instance is "the actual building constructed from that blueprint."

Step	Key Question	HANA KGE Feature	Covered in
[0] Competency Question	What business questions should this KG answer?	(design starting point)	Part 2-1 / 2-2 (starting point) + Part 4 (validation benchmark)
[1] Data Integration	How do I bring a BDC Data Product into HANA?	Virtual Table (no ETL)	Part 1 (this post)
[2-1] KG Creation — Ontology	How do I design classes and relationships?	(design phase)	Part 2-1 / 2-2
[2-2] KG Creation — Instance	How do I generate TTL from real data?	(generation phase)	Part 3
[3] Load	How do I import TTL into HANA KGE?	Triple Store: a dedicated graph store separated from relational data	Part 3
[4] Validation	How do I verify that the loaded KG is correct?	SHACL: W3C standard for graph data validation	Part 3 (introduced briefly)
[5] AI Agent Development	How do I combine SPARQL + SQL?	SPARQL_TABLE: run SPARQL directly inside SQL. Inference: derive relationships from OWL rules without explicit triples	Part 4 (SPARQL_TABLE in depth / Inference introduced briefly)

[0] CQ is not a step. It is the baseline for every step. It is not written once and set aside. At ontology design, it answers which classes are required; at validation, it tests whether the KG actually answers the question. The same question runs from the beginning of the series to the end. The Section 2 point, "the CQ runs through the series from start to finish," is also why the [0] row in this table appears in both Part 2-1/2-2 and Part 4.

A one-line preview of each feature:

Triple Store: Stores KG data in a space completely separate from relational tables, managed at graph granularity, with independent permission control.
SHACL (not covered in detail in this series): "This field must exist," "This value must be a number." Define the rules once, and they are checked automatically as data is loaded. AI answer quality follows from data quality.
SPARQL_TABLE: Query the KG with one line in the SQL Console, for example SELECT * FROM SPARQL_TABLE('...'). No separate SPARQL endpoint is required.
Inference (not covered in detail in this series): Derive relationships through RDFS/OWL rules without explicit triples. Declare Manager = Leader in the ontology, and Alice (a Manager) is automatically queryable as a Leader without modifying the data.

These four features form the core of HANA Cloud KGE. How each one is applied in practice is covered in the corresponding post in this series.

What's Next

If this principle holds, the next question is how to actually build it.

Part 2-1 – Ontology Standards and Concepts covers the standards and concepts: what an ontology is, Class vs Instance, and how the W3C standards (Direct Mapping and R2RML) define the translation from relational data to RDF. Part 2-2 – Designing the Ontology for SAP Data then walks through the practical design decisions we made for SAP data, including what to place in the KG versus leave in SQL, Class Partition, the resulting ontology, and how we used AI to draft it. The two posts work as a pair, but Part 2-2 is also designed to stand on its own.

Stack: SAP BDC Data Products · HANA Cloud KGE · FastAPI · React · Claude (Anthropic / AI Core) Code: github.com/claudiopark86/sap-bdc-kge-agent-workshop

References

Ontology Development 101: A Guide to Creating Your First Ontology — Noy & McGuinness, Stanford 2001. The standard introduction to ontology design methodology. The source for concepts covered throughout this series, including Competency Questions, Class vs Instance, and iterative design. https://protege.stanford.edu/publications/ontology_development/ontology101.pdf
Harnessing Half a Century of Knowledge: SAP's Journey of Enriching APIs with Metadata — SAP Community Blog. SAP's evolved metadata strategy and ODM vision. https://community.sap.com/t5/technology-blog-posts-by-sap/harnessing-half-a-century-of-knowledge-sap-s-journey-of-enriching-apis-with/ba-p/13578364

Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-1: Ontology Standards and Concepts

2026-07-04T15:45:03.995000+02:00

This blog is part of a blog series on building AI Agents with SAP BDC (Business Data Cloud) Data Products and SAP HANA Cloud Knowledge Graph Engine:

Knowledge Graph Agent on SAP HANA Cloud Series – Part 1: Why Knowledge Graph for SAP Data
Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-1: Ontology Standards and Concepts
Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-2: Designing the Ontology for SAP Data
Knowledge Graph Agent on SAP HANA Cloud Series – Part 3: Data Pipeline from BDC to HANA Cloud KGE
Knowledge Graph Agent on SAP HANA Cloud Series – Part 4: Building an Agent with SPARQL and SQL
Knowledge Graph Agent on SAP HANA Cloud Series – Part 5: Lessons Learned

This post covers the concepts and standards of ontology design. It explains what an ontology is, why it works well with LLMs, what the seven-step methodology from Stanford's Ontology Development 101 proposes, and what the W3C standards (Direct Mapping and R2RML) define when translating relational data into RDF. This is the most theoretically detailed post in the series, providing the vocabulary and references that underpin the design decisions in later posts.

💡 Reading guide. This post goes deep into theory and W3C standards. If you would rather see the practical SAP BDC decisions right away, you can skip ahead to Part 2-2 – Designing the Ontology for SAP Data. Part 2-2 is structured so that you can follow it without reading this post to the end, and you can return here when you want the background.

Table of contents:

What is an Ontology
- 1.1 Core concepts
- 1.2 Class vs Instance
- 1.3 Property: connecting nodes and carrying values (ObjectProperty / DatatypeProperty / Domain & Range)
- 1.4 Design principles (IRI, Competency Questions)
- 1.5 Labels, multilingual text, and synonyms (rdfs:label, language tags, skos:altLabel)
The Seven Steps of Ontology 101: the process we followed
From RDB to RDF: what the W3C standards define
- 3.1 Class definition
- 3.2 Instance data identification
- 3.3 Data attribute representation
- 3.4 Relationship representation
- Combined example
Three domain decisions we made on top of the standards

What this post covers

This post addresses the theory and standards within the series. It introduces what an ontology is, the seven-step methodology from Stanford's Ontology Development 101, and the two W3C standards (Direct Mapping and R2RML) that define how relational data is mapped to RDF, including what they automate and where domain decisions are required.

This material is the background knowledge for the decisions that follow (Class Partition, KG vs SQL classification, Relationship SQL Views). The decisions themselves are covered from Part 2-2 onward, so if you want to move directly to practical decisions, you can skip ahead to Part 2-2.

One practical use: the content of this post can also be provided to an LLM as a prompt. The seven-step methodology from Ontology 101, the W3C mapping rules (Table → Class, Row → Instance, and so on), and the conventions for defining classes and properties using RDFS/OWL vocabulary. Feeding this standards guide together with your domain information to a generative model produces ontology drafts that are much closer to W3C standards. This is what determines the quality of the "drafting with AI" approach we cover in Part 2-2.

1. What is an Ontology

1.1 Core concepts

Before building a Knowledge Graph, it is important to understand what an ontology is. Stated simply:

An ontology is an explicit definition of "what kinds of things exist in this world, and how they are connected."

For an ontology in the supply chain domain:

These kinds of things exist: WorkCenter, Product, Supplier, Plant
They are connected like this: WorkCenters produce Products, Suppliers provide Products

An ontology file is this information written in a machine-readable format (RDF/OWL).

Why build one? Ontology Development 101 puts it this way:

"Developing an ontology is akin to defining a set of data and their structure for other programs to use."

The goal is not the ontology itself. The goal is to define the structure and vocabulary of data that an AI Agent or application will consume. At its core, the value is common understanding: making it possible for humans, LLMs, and software agents to interpret the same concepts through the same vocabulary.

This is where SAP BDC and One Domain Model come in. ODM already defines a standard vocabulary across S/4HANA, including WorkCenter, SalesOrder, and Supplier. When you build an ontology, you use this vocabulary directly. The LLM already knows what these words mean. The KG is structured with the same vocabulary. The Agent writes SPARQL using the same vocabulary.

The "common understanding" that Ontology 101 advocates is, in the case of SAP data, already provided by One Domain Model. Half of ontology design is done before you begin.

# Ontology example (Turtle format)
bdc:WorkCenter a owl:Class ;
    rdfs:label "WorkCenter" ;
    rdfs:comment "Production work center" .

bdc:Product a owl:Class ;
    rdfs:label "Product" ;
    rdfs:comment "Material/product" .

bdc:producesProduct a owl:ObjectProperty ;
    rdfs:domain bdc:WorkCenter ;
    rdfs:range  bdc:Product ;
    rdfs:label  "produces product" .

1.2 Class vs Instance: the first distinction

When first encountering ontologies, the difference between Class and Instance is often confusing. This distinction is the starting point for the entire KG structure.

Class = concept. "There is a kind of thing called WorkCenter."
Instance = actual data. "Z_ASM3 is an actual WorkCenter that exists."

By analogy with a BDC Virtual Table:

KG concept	Example	Virtual Table analogy
Class	`bdc:WorkCenter`	Table schema (column definitions)
Instance	`bdc:WorkCenter_Z_ASM3`	One row in the table

This is why there are two files:

bdc_dp_ontology.ttl: class and relationship definitions (schema)
bdc_dp_instances.ttl: actual WorkCenter, Product, and Supplier data

There are as many instances as there are rows in the Virtual Table. With the demo data containing 129 WorkCenters, there are 129 instances.

1.3 Property: connecting nodes and carrying values

If Class and Instance describe "what exists," Property describes "how things are connected and what values they hold." RDF/OWL distinguishes two types of property:

Type	Value form	Example
`owl:ObjectProperty` (relationship)	IRI of another node	`bdc:WorkCenter_Z_ASM3 bdc:producesProduct bdc:Product_MZ-FG-C900`
`owl:DatatypeProperty` (attribute)	literal (string / number / date)	`bdc:WorkCenter_Z_ASM3 bdc:workCenterName "Z_ASM3"`

💡 If this is confusing: think of DatatypeProperty as "a regular column that does not lead to another table." A relational column such as WORK_CENTER.WorkCenterName, which simply holds a row's attribute, becomes a DatatypeProperty like bdc:workCenterName in the KG. Conversely, ObjectProperty resembles "a foreign key that points to another table." A column such as WORK_CENTER.PlantID, which points to another row, becomes an ObjectProperty like bdc:locatedAt in the KG.

This distinction is what makes a graph a graph. With only DatatypeProperties, each node would carry its own attributes but would not link to other nodes. They would be closer to isolated records than a connected graph. The moment ObjectProperty connects a node to another node, the records become a graph, and SPARQL can traverse chains such as "WorkCenter → Product → Customer."

In Turtle, both are declared with the same rdf:type syntax:

bdc:producesProduct a owl:ObjectProperty ;
    rdfs:domain bdc:WorkCenter ;
    rdfs:range  bdc:FinishedGood .

bdc:workCenterName a owl:DatatypeProperty ;
    rdfs:domain bdc:WorkCenter ;
    rdfs:range  xsd:string .

Domain & Range: applying type constraints to properties

Each property can carry type constraints through rdfs:domain and rdfs:range:

rdfs:domain: the class expected to appear as the subject of this property. "producesProduct is intended to be used with WorkCenter as its subject."
rdfs:range:
- For ObjectProperty: the class that can serve as the object. "The value of producesProduct is a FinishedGood."
- For DatatypeProperty: the XSD type of the value. xsd:string, xsd:integer, xsd:date, and so on.

Without these modeling guardrails, SPARQL queries may return invalid results, for example, a Supplier producing a product, or a Plant being produced. Domain and Range help both humans and LLMs use the intended classes when writing SPARQL queries.

Practical guidance (Ontology 101):

Use the most general class for Domain and Range. If you want to include every Product, use bdc:Product instead of bdc:FinishedGood.
Do not make the range too broad either (setting it to owl:Thing carries no meaning).
All subclasses are automatically included. If the range is bdc:Product, its subclasses (FinishedGood/SemiFinished/RawMaterial) are included as well.

Edge case: DatatypeProperty vs ObjectProperty

There are cases where it is not obvious whether a value should be a "plain string" or "a separate node." For example, the country of a supplier:

If a simple value is sufficient → owl:DatatypeProperty (bdc:country "DE"^^xsd:string)
If multiple systems or multiple classes reference the same country, or if the country itself needs a label or description → model the country as a separate node and use owl:ObjectProperty (bdc:locatedInCountry bdc:Country_DE)

The latter is the pattern that turns a KG into an "extensible asset," but for simple representations, a DatatypeProperty is sufficient. This is a domain decision.

1.4 Design principles: IRI, Competency Questions

💡 IRI notation. In RDF, every resource (class, property, instance) is identified by an IRI (Internationalized Resource Identifier). You can think of it as a URL. The two are nearly the same for this discussion. Originally, it appears in the full URL form, such as <http://sap.com/bdc/WorkCenter>.
Why include the domain (URL)? To prevent collisions when the same name is used with different meanings across domains. For example, the Customer in one system and the Customer in another system may represent different concepts; embedding the domain in the IRI makes the two resources distinguishable. Both can be loaded into the same KG without collision, and when two KGs are later integrated, you can decide explicitly how to map them.
Writing the full URL every time becomes verbose, so Turtle allows prefix declarations as a shorthand. This series uses bdc: as the single prefix for the SAP BDC domain.
@prefix bdc:  <http://sap.com/bdc/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
From here on, bdc:WorkCenter (= <http://sap.com/bdc/WorkCenter>) and bdc:WorkCenter_Z_ASM3 (= <http://sap.com/bdc/WorkCenter_Z_ASM3>) can be written in this short form. Classes, relationships, properties, and instances are distinguished by naming conventions:

Type Convention Example
Class PascalCase bdc:WorkCenter, bdc:Customer
Relationship (ObjectProperty) camelCase, verb phrase bdc:producesProduct, bdc:hasAddress
Attribute (DatatypeProperty) camelCase bdc:country, bdc:customerID
Instance ClassName_identifier bdc:WorkCenter_Z_ASM3, bdc:Customer_0001000010
This convention follows the practice of community-standard RDF vocabularies such as schema.org and FOAF. Most code examples in this series use the abbreviated form. The W3C standard examples in Section 3 (<People/ID=7>) use full IRIs without prefixes. Both forms represent the same IRI notation.
For extension: separate prefixes by domain. We start with the single SAP BDC domain, so a single bdc: prefix is enough. As the KG expands into other domains, the standard RDF convention is to introduce a separate prefix per domain. For example, when integrating data from another SAP product, or external systems such as logistics information or third-party master data, those would be placed under a different prefix and domain URL so the two vocabularies do not collide. Rather than packing everything into bdc:, prefixes are added along domain boundaries. This is the prefix-level realization of the "KG as an extensible asset" point emphasized in Part 1 Section 6.

📖 Terminology note: In Description Logic and KG literature, the two layers are called T-Box (Terminological Box, definitions of classes and relationships, the schema) and A-Box (Assertion Box, the actual instance facts). The two TTL files in our project correspond exactly to these layers: bdc_dp_ontology.ttl is the T-Box, and bdc_dp_instances.ttl is the A-Box.

Competency Questions: write the questions before designing

Ontology Development 101 (Noy & McGuinness, Stanford 2001) emphasizes one core principle:

"Before designing an ontology, write down the questions this KG must answer."

These are called Competency Questions. Defining the questions first determines naturally which classes and relationships are needed.

The Competency Questions for our project:

Question	What is needed
"What finished goods does Z_ASM3 produce?"	`bdc:WorkCenter` `bdc:producesProduct` `bdc:FinishedGood`
"What is the per-customer revenue exposure for these finished goods?"	SQL (No KG required. Transactional data)
"What products does this supplier provide?"	`bdc:Supplier` `bdc:fromSupplier` `bdc:forProduct` `bdc:PurchasingSourceList`
"Which finished goods does this raw material go into?"	`bdc:hasComponent` (Product → Product)

Once the questions are written, three things are determined:

Which classes are needed: the nouns in the question.
Which relationships are needed: the verbs in the question.
What goes into the KG versus what stays in SQL: relationships requiring SPARQL traversal go into the KG; numeric aggregation stays in SQL.

These questions later serve as SPARQL test cases. After loading, if SPARQL returns the correct answer for each question, the ontology is well designed.

1.5 Labels, multilingual text, and synonyms: rdfs:label, language tags, skos:altLabel

💡 Reading note. This section is longer because labels, comments, and synonyms directly affect how well an AI Agent interprets KG results. If you already know RDFS/SKOS annotations, you can skim this section and continue with Section 2.

rdfs:label and rdfs:comment: the basics

In a KG, attaching rdfs:label to every Class, Property, and Instance is standard practice. Without labels, SPARQL results return only URIs such as bdc:WorkCenter_Z_ASM3, which are hard for an LLM to interpret. rdfs:comment adds a short description that helps the LLM understand the role of each class or property when ontology context is provided. Practical authoring rules are covered in Part 2-2.

Multilingual: language tags

Attaching a language tag to the same property supports multiple languages at once.

bdc:WorkCenter a owl:Class ;
    rdfs:label   "WorkCenter"@en ,
                 "작업장"@ko ;
    rdfs:comment "Production work center."@en ,
                 "생산 작업장."@ko .

In SPARQL, FILTER(LANG(?label) = "ko") selects the desired language. This works because RDF stores "작업장"@ko and "WorkCenter"@en as distinct literals from the start. The language tag is part of the value itself, and SPARQL's LANG() function reads it. This works by default, with no additional configuration required.

Synonyms: reusing skos:altLabel

rdfs:label provides a human-readable name, but it does not distinguish between preferred and alternative names. In natural language search or GraphRAG contexts, the same node must be discoverable whether the user searches for "supplier" or "vendor." For this, a way to represent synonyms is required.

This is where we reuse SKOS (Simple Knowledge Organization System, W3C 2009 Recommendation) and its skos:altLabel. SKOS is originally a standard for classification systems and controlled vocabularies. Its central concept, skos:Concept, represents "a unit of thought," such as a classification value or a category item. This is different from an OWL Class or instance such as bdc:WorkCenter in our KG.

The three SKOS labels:

skos:prefLabel: preferred form (one per language is recommended)
skos:altLabel: synonyms, abbreviations, and notation variants (no count limit)
skos:hiddenLabel: labels indexed for search but not displayed (typos, deprecated forms, and so on)

All three are sub-properties (rdfs:subPropertyOf) of rdfs:label. That is, attaching prefLabel already implies rdfs:label.

skos:altLabel does not enforce rdfs:domain of skos:Concept. The SKOS specification intentionally omits a domain so that altLabel can be attached to resources of any type. Using skos:altLabel on a class or a skos:Concept, is a borrowed use of the property.

Target	Meaning	Example	skos:altLabel
`skos:Concept`	A classification value being referenced	Categories such as "Domestic Supplier," "Overseas Supplier"	Native use
`owl:Class`	A set with members	"There is a kind called Supplier"	Borrowed
Instance	An actual entity	Real Suppliers such as "USSU-VSF01," "USSU-VSF02"	Borrowed

bdc:Supplier (Class)
    ├── USSU-VSF01  →  hasRole  →  c_domestic   (Domestic Supplier)
    └── USSU-VSF02  →  hasRole  →  c_overseas   (Overseas Supplier)

c_domestic, c_overseas  →  skos:Concept (classification values)

Domestic/overseas classification can also be expressed via a DatatypeProperty. skos:Concept is used when the classification value itself must be modeled as an independent concept, for example when it is shared across multiple systems or requires its own label or description.

Borrowing on a class (the approach used in this project):

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

bdc:Supplier a owl:Class ;                # owl:Class — borrowed use
    rdfs:label    "Supplier"@en ,
                  "공급사"@ko ;            # preferred name (for display)
    skos:altLabel "공급업체"@ko ,          # synonym (for search)
                  "벤더"@ko ,
                  "Vendor"@en ;
    rdfs:comment  "A counterparty that supplies materials or services."@en .

The same pattern applies to instances:

ex:successFactors a ex:Product ;            # Instance — also borrowed
    rdfs:label    "SAP SuccessFactors"@en ;
    skos:altLabel "SuccessFactors"@en ;
    skos:altLabel "SFSF"@en ;
    skos:altLabel "석세스팩터스"@ko .        # Korean notation

In this project, the pattern is applied only at the class level. Instance-level synonyms would require leveraging source columns (Virtual Table) or building a separate mapping, which is outside the scope of these examples.

The line not to cross is this: if synonyms are needed, do not change the resource type to skos:Concept. That would be a misuse. bdc:Supplier remains an owl:Class, ex:successFactors remains an instance, and only skos:altLabel is layered on top.

To search across the preferred name and synonyms in a single SPARQL query, use property path alternation (|) :

SELECT ?class ?label WHERE {
  ?class a owl:Class .
  ?class rdfs:label|skos:altLabel ?label .
  FILTER(CONTAINS(LCASE(?label), LCASE("vendor")))
}

📖 Standard basis: The SKOS Reference (W3C Recommendation, 2009) does not declare a domain on skos:altLabel, and presents graphs attaching labels to owl:Class as official examples. This is not an informal workaround but a legitimate use that the standard explicitly permits. https://www.w3.org/TR/skos-reference/

Can synonyms work without SKOS?

Yes. A synonym is ultimately just a triple, and can be expressed without SKOS. The important point is that SKOS does not "enable" synonyms in the first place.

The simplest approach is to define a custom property:

ex:successFactors a ex:Product ;
    rdfs:label "SAP SuccessFactors"@en ;
    ex:alias   "SFSF"@en, "SuccessFactors"@en, "석세스팩터스"@ko .

ex:alias is a custom property. Search works exactly the same way (?p rdfs:label|ex:alias ?label). For GraphRAG-style search alone, this is sufficient.

Alternatively, all variants can be packed into rdfs:label, and search will still work. The trade-off is that the distinction between preferred and alternative forms disappears, so "which one to show as the primary form in a UI" becomes ambiguous.

So what does SKOS provide in addition? All three approaches deliver the same "synonym search." The value of SKOS lies elsewhere:

	`ex:alias`(custom) ⭕	`rdfs:label`packed⭕	`skos:altLabel`⭕
Synonym search	⭕	⭕	⭕
Preferred/alternative role distinction	Build it yourself	❌	⭕built in (pref/alt/hidden)
Standard (recognized by tools and people)	❌custom property	△	⭕W3C
Cross-system alignment anchor	❌	❌	⭕(mapping properties)

Borrowing skos:altLabel is not purely about future-proofing. Its value spans two time horizons:

Immediate value: as a standard, other tools and people immediately recognize it as "a synonym," and the role distinction (pref/alt/hidden) is predefined, so there is no need to reinvent the wheel.
Future value: when extending into cross-system mapping (skos:exactMatch and similar), the same vocabulary family is reused.

When to use what

What you need	Approach
One preferred name	`rdfs:label`
Synonyms, abbreviations	`skos:altLabel`
Multilingual preferred name	`rdfs:label "이름"@ko , "Name"@en`
Multilingual synonyms	`skos:altLabel "벤더"@ko , "Vendor"@en`
Classification or code system	`skos:Concept` + `skos:prefLabel` / `skos:altLabel` (out of scope for this example; extend when needed)

Typical situations where synonyms must be attached:

GraphRAG or natural language search: the same node must be discoverable regardless of how the user phrases the query.
Multilingual environments: a single concept must be searchable in both English and Korean.
System integration: terms from other systems must be marked as representing the same concept.

📖 Reference: The concepts covered in this section (Competency Questions, Class vs Instance, Domain & Range) are based on Ontology Development 101 (Noy & McGuinness, Stanford 2001), the standard introduction to ontology design. https://protege.stanford.edu/publications/ontology_development/ontology101.pdf

2. The Seven Steps of Ontology 101: The Process We Followed

The concepts covered in Section 1 (Class/Instance, Domain & Range, Competency Questions) all originate from Stanford's Ontology Development 101. This guide does not just enumerate concepts. It proposes a seven-step process for building an ontology.

We followed this seven-step process directly when designing the BDC Data Products-based KG. Before going into the practical work in the following sections, here is the high-level mapping.

The seven-step process

Step	Original step	Meaning	*Mapping in our project*
1	Determine the domain and scope	Determine domain and scope (with Competency Questions)	"How far does the impact spread when Z_ASM3 stops?" (the four CQs from Section 1)
2	Consider reusing existing ontologies	Evaluate reuse of existing ontologies	One Domain Model: standard vocabulary (`WorkCenter`, `Supplier`, `Product`) used as-is
3	Enumerate important terms	Enumerate important terms	Exploring entities and column names from BDC Virtual Tables (Part 3 Section 1)
4	Define classes and class hierarchy	Define classes and the class hierarchy	`MasterData`/`StructuralNode` upper layer + six classes (including the Product partition in Part 2-2)
5	Define properties of classes	Define the properties of classes	`producesProduct`, `locatedAt`, `hasComponent`, and other ObjectProperties
6	Define facets of properties	Define property facets (cardinality, value type)	Domain/Range constraints, `owl:disjointWith` (Part 2-2)
7	Create instances	Create instances	Part 3 Section 5 (Relationship Views → TTL triples)

If you remember one thing: iteration is the essence

The point that Ontology 101 emphasizes most is that "it is never completed in one pass."

"Designing an ontology is necessarily an iterative process."

Attempting to model an entire domain in one pass is rarely realistic:

Scope is hard to bound: the boundary of "how far to model" becomes unclear.
Completion is hard to verify: without a defined test scope, the quality benchmark is unclear.
Project milestones are hard to set: schedules and deliverables blur, making productization difficult.

After one full pass through the seven steps, you have the minimum KG required to answer the first CQ. When a new CQ arrives, you return to Step 1 and run the cycle again.

To borrow the book's phrasing:

"Develop the ontology incrementally, one competency question at a time."

Class Partition (Part 2-2), the Relationship SQL View (Part 3 Section 3), and the decision to leave Customer in SQL (Part 2-2) were not produced in the first iteration. They were solutions to problems discovered while validating the CQs.

📖 Source: Noy, N. F., & McGuinness, D. L. (2001). Ontology Development 101: A Guide to Creating Your First Ontology. Stanford KSL Technical Report. https://protege.stanford.edu/publications/ontology_development/ontology101.pdf

3. From RDB to RDF: What the W3C Standards Define

ℹ️ Where this section sits: If Section 1 and Section 2 dealt with the ontology (schema) itself, this section covers its counterpart, the instance (data) translation standard. The two together make a KG. What Section 2 calls Step 7 (Create Instances) in the Ontology 101 process is exactly what the W3C standardized here.

So far we have covered "what an ontology is" and "how to design one." When data already lives in a relational database, as with SAP BDC, the question of how to translate it into RDF triples was standardized by the W3C in 2012.

The automatic translation by the standard alone is not sufficient. SAP data often involves business relationships that span multiple tables, that exist without FK declarations, or that require a single table to be split into multiple classes. A more flexible approach is needed. For this reason, the W3C standardized both automatic translation (Direct Mapping) and custom mapping (R2RML) together.

📐 R2RML produces instance data, not ontology
R2RML is frequently misunderstood at first encounter. "Does this produce an ontology, or instance data?" The answer is instance data. R2RML is a file that contains only transformation rules such as "map this row of this table as an instance of which class, and map this column as which property." The class definitions themselves (bdc:Supplier is a class with the following properties) live in a separate ontology file, and R2RML simply references them.
Three files form a useful mental model:
File What it contains Example
Ontology file Class and property definitions (the blueprint) bdc:Supplier a owl:Class
R2RML mapping file The rule "take a row from this table (or the result of this SQL query) and convert it to instance data according to that blueprint" Row of SUPPLIER_MASTER = instance of bdc:Supplier
Instance data The actual data triples bdc:Supplier_S001 a bdc:Supplier ; bdc:name "ACME"

There are two standards:

	Direct Mapping	R2RML
Translation method	Automatic, based on schema	Mapping file authored manually
Class / relationship / attribute names	Table and column names used as-is (`Person_table`, `Person_table#name`)	Free to assign business vocabulary (`bdc:Supplier`, `bdc:hasComponent`, `bdc:supplierName`)
When to use	When every table maps cleanly to a single class and FKs accurately express all business relationships	When one table needs to be split into multiple classes (for example, splitting `MaterialType` into FinishedGood/SemiFinished/RawMaterial), when FKs are missing or relationships span multi-hop chains, or when ABAP abbreviations (`EKKO`, `KNA1`) need to be replaced with business vocabulary (`PurchaseOrder`, `Customer`)

Direct Mapping provides the baseline automatic mapping from relational data to RDF, while R2RML provides a customizable mapping language for cases where the default mapping is not sufficient. Below, each of the four mapping types is presented side by side as "what Direct Mapping does automatically" versus "what R2RML / our project actually did."

📝 Note: Our project did not use an R2RML engine directly. We generated triples using Python scripts, but the principles are identical to those defined by R2RML.

A preview of R2RML standard vocabulary

Sections 3.1–3.4 below cover the four mapping types. Before entering the detail, here is a preview of how our SQL View and Python approach maps to R2RML standard vocabulary, limited to the three core constructs. As you read Sections 3.1–3.4, recognizing "this corresponds to that R2RML construct" is sufficient.

R2RML construct	What the standard defines	Step in Section 3
`rr:tableName`	Designates a single table as the mapping input source	Section 3.1: single table → single class
`rr:sqlQuery`	Designates an arbitrary SQL SELECT result as the mapping input source	Section 3.1: multiple tables JOINed → single class (for example, SUPPLIER_MASTER + DETAIL → `bdc:Supplier`) / Section 3.4: multi-hop relationship View
`rr:joinCondition`	Joins two tables inside a RefObjectMap to produce relationship triples	Section 3.4: FK join is precomputed inside the View; two IRIs are exposed together in a single row

This table pairs only "what (Instance Data)" and "how connected (Relationship)." The IRI construction in Section 3.2 Instance Data Identification (rr:subjectMap) and the column → attribute mapping in Section 3.3 Data Attribute (rr:predicateObjectMap of literal form) are straightforward and not given separate rows.

Inverting this view yields the picture of using the DB itself as the mapping engine, without a separate R2RML processing engine. When a View exposes every necessary column in a single row (the subject's ID and the relationship target's ID), the JOIN that an R2RML engine would perform inside its mapping is already done by the database. The output (relationship triples) is the same.

📌 The Relationship SQL View pattern in Part 3 is precisely this picture. The HANA SQL Views (KGR_*) precompute multi-hop JOINs, and the TTL generation script reads those Views to write relationship triples directly. The transformation semantics defined by the standard are followed exactly, without a separate mapping engine.

ℹ️ Note: another mode. The discussion above assumes the "materialize relationship triples ahead of time and write them into the graph" approach. The standard defines another mode as well. Instead of materializing triples in advance, joinConditions are translated into SQL JOINs on the fly each time a SPARQL query arrives. This series follows the materialized approach.

3.1 Class definition

W3C Direct Mapping

One table becomes one class. Each row is automatically translated into an instance triple of that class.

<People/ID=7> rdf:type <People> .

However, the class definition itself is not generated. Direct Mapping outputs only instance triples. The declaration that <People> is a class must be written separately.

<People> rdf:type rdfs:Class ;
         rdfs:label "Person" ;
         rdfs:comment "Business entity representing a person" .

R2RML / our project

Direct Mapping's "1 Table = 1 Class" fits simple relational databases well, but real SAP data is different. Class and Table are not a 1:1 correspondence.

1 Table → N Classes (partition): when a single table contains multiple kinds of entities. The BDC Product table is split into three classes based on the MaterialType column.

BDC_DP.PRODUCT (single table)
    MaterialType = FERT  →  bdc:FinishedGood
    MaterialType = HALB  →  bdc:SemiFinished
    MaterialType = ROH   →  bdc:RawMaterial

N Tables → 1 Class (consolidation): when multiple tables form a single business concept. WorkCenter and WorkCenterCapacity are separate tables, but in the KG they are represented by a single class bdc:WorkCenter.

"Which data belongs to which class" is determined by Competency Questions and domain decisions, not by table schema. Class Partition is covered in detail in Part 2-2.

In our project, bdc_dp_ontology.ttl is the file that holds the class definitions.

3.2 Instance data identification

W3C Direct Mapping

Each row becomes an instance (node) in the KG. It is identified by an IRI that combines the table name and the primary key value.

<People/ID=7>                   # single PK
<Order/customer=7;item=42>      # composite PK separated by ;

R2RML / our project

The IRI format itself is free. The standard simply provides a guide for "how names are constructed during automatic translation." We define readable forms such as bdc:Person_7 directly.

In our project, each row of a BDC Virtual Table generates an instance IRI in this pattern.

bdc:Person_7 a bdc:Person ;
    rdfs:label "Bob" .

💡 Always attach rdfs:label to instances. IRIs are identifiers, not human-readable names. SPARQL results returning only IRIs are difficult for an LLM to interpret.

3.3 Data attribute representation

W3C Direct Mapping

Each column of a table is translated into a literal property. The predicate name is automatically generated in the tableName#columnName form. For example, the fname column of the People table becomes <People#fname>.

<People/ID=7> <People#fname> "Bob" .
<People/ID=7> <People#ID>    7 .

NULL values do not produce triples.

R2RML / our project

Predicate names can be replaced with business vocabulary. fname is the column name, but the business term name is more appropriate, so we define bdc:name directly. Property definitions (domain, range, label) must be written separately in the ontology TTL.

# Defined in ontology TTL
bdc:name rdf:type owl:DatatypeProperty ;
    rdfs:domain bdc:Person ;
    rdfs:range  xsd:string ;
    rdfs:label  "Name" .

# Used in instance TTL
bdc:Person_7 bdc:name "Bob" .

3.4 Relationship representation

W3C Direct Mapping

A single FK column produces two triples.

<People/ID=7> <People#addressID>     18 .                    # the value itself (literal triple)
<People/ID=7> <People#ref-addressID> <Addresses/ID=18> .     # the reference (reference triple)

literal triple: preserves the original FK value.
reference triple: a graph edge pointing to another instance.

However, the predicate name is fixed in the #ref-colName form and cannot carry business meaning. Furthermore, Direct Mapping creates a reference triple only when an FK is declared.

R2RML / our project

R2RML does not require FK declarations. As long as the values exist, a relationship can be created.

If FKs cover 100% of relationships, Direct Mapping alone may be sufficient. In real SAP data, two reasons make this rarely the case.
First, once classes are split, the relationships between those classes must be defined explicitly. When MaterialType partitions Products into FinishedGood / SemiFinished / RawMaterial, the relationships among them (such as hasComponent) are determined by domain analysis, not by FKs.
Second, when a business relationship spans multiple tables (multi-hop), a single FK cannot connect them directly. This is why we precompute relationships with SQL Views to flatten them into 1-hop edges.
Ultimately, relationships are determined by people who know the domain, not by FKs.

There are three approaches to creating relationships:

Approach A: Assemble the IRI directly from a value (simple case)

Take the value of the FK column and construct an IRI directly. There is no need to look at the neighboring table. If addressID is 18, construct the IRI bdc:Address_18 and create the relationship triple.

bdc:Person_7 bdc:hasAddress bdc:Address_18 .

Approach B: Precompute the relationship with a SQL View (complex case)

For multi-hop or complex JOIN relationships, we precompute with a SQL View. The View returns (subj_id, obj_id) pairs, and Python reads them to build triples.

-- KGR_WC_PRODUCES_PRODUCT View result (example)
subj_id      | obj_id
-------------|----------
Z_ASM3       | MZ-FG-C900
Z_ASM3       | MZ-FG-C950

→ bdc:WorkCenter_Z_ASM3 bdc:producesProduct bdc:FinishedGood_MZ-FG-C900

Our project's KGR_WC_LOCATEDAT_PLANT, KGR_WC_PRODUCES_PRODUCT, and others use this approach.

Approach C: Connect by shared column, even without FK (simple case)

Even without an FK constraint, if both tables share a column with the same meaning, Approach A applies directly. For example, the People table and the Addresses table are linked by addressID, but no FK is declared:

People table                       Addresses table
ID=7, addressID=18     →           ID=18, city=Seoul
      ↓ no FK declared
      Use addressID value 18 to build the IRI → bdc:Address_18

→ bdc:Person_7 bdc:hasAddress bdc:Address_18

The relationship works as long as the value exists. Our SQL Views also operate independently of whether FKs are declared.

In practice, all three are used. Simple FK relationships use Approach A, connections without FKs use Approach C, and complex multi-hop relationships use Approach B. The right choice depends on the situation, and all three approaches appeared in our project.

	Direct Mapping	R2RML / our project
FK declaration required	Yes	No (values are enough)
Relationship name	Fixed as `#ref-colName`	Free (`bdc:hasAddress`, business vocabulary)
Defined by	Machine (W3C spec)	Human (domain expert)
Multi-hop	Not supported (only direct FK)	Supported via precomputed SQL Views, flattened to 1-hop

Combined example: how two tables become a graph

Original SQL tables

-- People table
ID  | fname | addressID
----+-------+----------
7   | Bob   | 18

-- Addresses table
ID  | city
----+------
18  | Seoul

Step 1: Direct Mapping automatic result

<People/ID=7>     rdf:type <People> .
<Addresses/ID=18> rdf:type <Addresses> .
<People/ID=7>     <People#fname>           "Bob" .
<People/ID=7>     <People#addressID>       18 .
<Addresses/ID=18> <Addresses#city>         "Seoul" .
<People/ID=7>     <People#ref-addressID>   <Addresses/ID=18> .

The data has been translated, but the predicates carry technical names (<People#fname>, <People#ref-addressID>).

Step 2: Layer an ontology to add business meaning

# ontology TTL
bdc:Person   rdf:type owl:Class ; rdfs:label "Person" .
bdc:Address  rdf:type owl:Class ; rdfs:label "Address" .
bdc:hasName    rdf:type owl:DatatypeProperty ;
               rdfs:domain bdc:Person ; rdfs:range xsd:string .
bdc:hasAddress rdf:type owl:ObjectProperty ;
               rdfs:domain bdc:Person ; rdfs:range bdc:Address .
bdc:inCity     rdf:type owl:DatatypeProperty ;
               rdfs:domain bdc:Address ; rdfs:range xsd:string .

# instance TTL (with business vocabulary)
<People/ID=7>     rdf:type bdc:Person ;
                  rdfs:label "Bob" ;
                  bdc:hasName "Bob" ;
                  bdc:hasAddress <Addresses/ID=18> .
<Addresses/ID=18> rdf:type bdc:Address ;
                  rdfs:label "Seoul" ;
                  bdc:inCity "Seoul" .

The standard's automatic mapping is the starting point; layering ontology definitions to add business meaning is the destination.

📖 Sources:
W3C, A Direct Mapping of Relational Data to RDF (Recommendation, 2012-09-27). https://www.w3.org/TR/rdb-direct-mapping/
W3C, R2RML: RDB to RDF Mapping Language (Recommendation, 2012-09-27). https://www.w3.org/TR/r2rml/

4. Three Domain Decisions We Made on Top of the Standards

The mappings defined by the W3C standards work well for simple relational databases. For data with a rich business domain inside, such as SAP BDC Data Products, a few domain decisions on top of the standard mappings are required to make the KG genuinely useful. We encountered three such points in our project.

Decision 1. Class Partition: one table, multiple classes

The default behavior of Direct Mapping is to map one table to one class. This is sufficient for simple RDBs, but in SAP's Product table, finished goods, semi-finished, and raw materials are mixed in the same table and distinguished only by the MaterialType column. Mapped as-is, all three would become a single bdc:Product.

→ Decision: assign different classes per row based on a discriminator column. Covered in detail in Part 2-2.

Decision 2. Multi-hop relationships: business relationships beyond direct FKs

Direct Mapping creates reference triples only from declared FKs. This has two implications.

(a) If an FK constraint is missing from the schema, no relationship triple is produced. The column value remains as a literal, and the two entities are not connected.

(b) A relationship requires a direct FK. SAP S/4HANA business relationships are often expressed through several intermediate tables. The relationship between WorkCenter and finished goods, for example, spans three routing tables, forming a 4-hop chain. This can be expressed with R2RML join conditions, but we chose a simpler approach.

→ Decision: precompute multi-hop chains with SQL Views and flatten them into 1-hop relationships. Covered in detail in Part 3 Section 3.

Decision 3. Junction tables: keep as node, or flatten

N:N relationships in SQL are typically expressed via junction tables (intermediate tables linking two tables). In our demo, PurchasingSourceList (PSL) is such a junction: a list of suppliers approved to provide each product.

When moving such a junction into a KG, there are two options.

Option 1. Keep as a node (Direct Mapping's default behavior): PSL becomes a separate node in the graph, with relationships connecting it to both sides.

→ The PSL node serves as a bridge between Supplier and Product. PSL can carry additional attributes such as plant, validity period, and priority.

Option 2. Flatten (direct relationship): drop the PSL node and connect Supplier directly to Product.

→ Cleaner, but the additional information PSL carries disappears. For example, if the same supplier-product pair has a different priority per plant, or if expired registrations must be distinguished from current ones, that information is lost. The fact that "Supplier A supplies Product X" remains, but "when, at which plant, with what priority" can no longer be answered by the KG.

Our decision: PSL is not a simple N:N connection. It carries additional business information (plant, validity period, priority), so it is kept as a node. Two relationships are made explicit in the ontology.

bdc:fromSupplier a owl:ObjectProperty ;
    rdfs:domain bdc:PurchasingSourceList ;
    rdfs:range  bdc:Supplier .

bdc:forProduct a owl:ObjectProperty ;
    rdfs:domain bdc:PurchasingSourceList ;
    rdfs:range  bdc:Product .

→ PSL is placed in the graph as the class bdc:PurchasingSourceList, connected to both sides via bdc:fromSupplier and bdc:forProduct.

→ The decision criterion is whether the junction represents a simple connection or carries additional meaning. A junction that expresses only a simple connection should be flattened. The ontology result in Part 2-2, where PSL is classified as a bdc:StructuralNode (bridge node), reflects this decision.

Standard mapping vs our decisions: at a glance

Standard default	Our domain decision	Where
1 Table = 1 Class	Class Partition by discriminator column	Part 2-2
Reference triples only from direct FKs	Multi-hop precomputed into 1-hop via SQL Views	Part 3 Section 3
Junction table represented as an intermediate node	Meaningful junctions kept as nodes; simple connections flattened	Part 2-2

These three decisions are the domain-level additions we layered when translating the SAP BDC domain into a KG. The standard mapping provides a baseline; the domain decisions add business meaning on top.

The actual application of these decisions begins in the next post (Part 2-2).

Summary

This post covered:

Core ontology concepts: Class/Instance (T-Box/A-Box), Domain & Range, Competency Questions, and LLM affinity all rooted in Ontology 101.
The seven-step process of Ontology 101: from determining the domain to creating instances. Iteration is the essence.
W3C RDB→RDF mapping standards: Direct Mapping (automatic) and R2RML (manual and flexible). Table → Class, Row → Instance, Column → Literal Property, FK → ObjectProperty.
A preview of domain decisions on top of the standards: Class Partition, multi-hop, junction handling, covered as concrete decisions in the next post.

What's Next

The background is now in place. From here on, we move into the actual decisions we made for SAP BDC data.

Part 2-2 – Designing the Ontology for SAP Data covers the domain decisions we made on top of these standards: which entities to place in the KG and which to leave in SQL, why we split a single Product table into three classes, what the final ontology structure looks like, and how we used AI to draft the ontology.

Stack: SAP BDC Data Products · HANA Cloud KGE · FastAPI · React · Claude (Anthropic / AI Core) Code: github.com/claudiopark86/sap-bdc-kge-agent-workshop

References

Ontology Development 101: A Guide to Creating Your First Ontology by Noy & McGuinness, Stanford 2001. https://protege.stanford.edu/publications/ontology_development/ontology101.pdf
A Direct Mapping of Relational Data to RDF, W3C Recommendation, 2012-09-27. https://www.w3.org/TR/rdb-direct-mapping/
R2RML: RDB to RDF Mapping Language, W3C Recommendation, 2012-09-27. https://www.w3.org/TR/r2rml/

Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-2: Designing the Ontology for SAP Data

2026-07-04T15:45:25.498000+02:00

This blog is part of a blog series on building AI Agents with SAP BDC (Business Data Cloud) Data Products and SAP HANA Cloud Knowledge Graph Engine:

Knowledge Graph Agent on SAP HANA Cloud Series – Part 1: Why Knowledge Graph for SAP Data
Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-1: Ontology Standards and Concepts
Knowledge Graph Agent on SAP HANA Cloud Series – Part 2-2: Designing the Ontology for SAP Data
Knowledge Graph Agent on SAP HANA Cloud Series – Part 3: Data Pipeline from BDC to HANA Cloud KGE
Knowledge Graph Agent on SAP HANA Cloud Series – Part 4: Building an Agent with SPARQL and SQL
Knowledge Graph Agent on SAP HANA Cloud Series – Part 5: Lessons Learned

This post covers the ontology design decisions we made for real SAP BDC data: which entities to place in the KG versus leave in SQL, why we split a single Product table into three classes, what the final ontology structure looks like, and how we used AI to draft the Turtle file, including multilingual labels, comments, and synonyms.

💡 Reading guide. This post is designed to stand on its own. Section 0 below briefly covers the minimum KG modeling vocabulary required to follow along (the table/row/column/relationship-link mapping and why rdfs:label matters). Section 1 prepares the environment, and the substantive work begins in Section 2. If you want the deeper W3C standards background and the conceptual foundation, consult Part 2-1 – Ontology Standards and Concepts.

📁 Code reference. All scripts and project files mentioned in this post are available in the demo repository: github.com/claudiopark86/sap-bdc-kge-agent-workshop
File names such as 00_hana_setup.sql, 01_setup_synonyms.py, 02_verify_joins.py, dp_mapping.yaml, and 04_generate_ontology.py refer to files in that repository.

Table of contents:

KG vocabulary essentials
Preparing the work environment: BDC connection, users, synonyms
Organizing your data as ontology material
Deciding between KG and SQL
Splitting one Data Product into multiple classes (Class Partition)
Completing the ontology
Drafting the ontology Turtle with AI, and writing labels

0. KG Vocabulary Essentials

Before moving into the work itself, here is the minimum KG modeling vocabulary required to follow this post. If you have read Part 2-1 in detail, this is a brief refresher; if you are seeing it for the first time, this much is sufficient to follow Sections 2–6.

0.1 Relational DB → KG mapping (at a glance)

The core mapping between a relational database and an RDF Knowledge Graph, as defined by the W3C:

Relational DB	Knowledge Graph	Example
Table	Class (concept)	`WORK_CENTER` table → `bdc:WorkCenter` class
Row	Instance (actual entity)	Row Z_ASM3 → `bdc:WorkCenter_Z_ASM3` instance
Column	DatatypeProperty (attribute / literal property)	`WorkCenterName` → `bdc:workCenterName "Z_ASM3"`
Relationship link (FK and similar)	ObjectProperty (relationship)	`PlantID` → `bdc:locatedAt bdc:Plant_1010`

⚠️ This table shows the basic mapping principles. In practice, the correspondence is rarely 1:1. A single table may be split into multiple classes (for example, splitting MaterialType into FinishedGood/SemiFinished/RawMaterial via Class Partition), or conversely, multiple tables may form a single class (for example, WorkCenter + WorkCenterCapacity → bdc:WorkCenter). These domain decisions are covered in Section 4 of this Part and in Part 2-1 Sections 3–4.

The key point is that relationship links are what make a graph a graph. More precisely: an FK (or a column shared between two tables) is a hint that "these two entities can be connected." Which business meaning to assign to that connection, and which name (ObjectProperty) to use, is a decision made by a domain expert. Direct Mapping looks at an FK and automatically produces a reference triple of the form #ref-colName; in R2RML, a person explicitly defines a business term such as bdc:locatedAt. The details are covered in Part 2-1 Section 3.

📖 Standard basis: The mapping above is grounded in the W3C Direct Mapping and R2RML recommendations (2012). The full standard definitions and the standard's limitations are covered in Part 2-1 Sections 3–4.

0.2 `rdfs:label` is the minimum requirement for a KG

Once instances are loaded into a KG, SPARQL results return URIs:

bdc:Supplier_1000015
bdc:Product_MZ-FG-C900
bdc:WorkCenter_Z_ASM3

An LLM given only URIs has a hard time interpreting "what this is." Attach rdfs:label to every instance, class, and property, and the SPARQL results return human-readable names directly.

wcLabel       | productLabel
Z_ASM3        | C-Series Road Bike 900
Z_ASM3        | C-Series Road Bike 950

Without labels, the KG functions, but the Agent cannot interpret the results. Labels are the minimum requirement that makes a KG into "a graph an LLM can read."

Not only labels but comments, and not only on instances but on classes and relationships too

The instance example above illustrates "why a label is needed." In an actual ontology, one more property is required, and the places where label and comment are attached extend further.

rdfs:comment: where label provides "a short name," comment is a natural-language description. A one-line answer to "what is a WorkCenter?"
Attached to classes and relationships (ObjectProperty) as well: not only on instances but on the class definitions themselves (T-Box). Tools such as Protégé and Metaphactory display labels instead of URIs, and when the Part 4 Agent loads ontology metadata into its LLM context, comments serve as the explanation of "what role this class plays."

bdc:WorkCenter a owl:Class ;
    rdfs:label   "WorkCenter"@en, "작업장"@ko ;
    rdfs:comment "Production work center. Located in a Plant, produces Finished Goods."@en,
                 "생산 작업장. 특정 Plant 에 위치하며 FinishedGood 을 생산한다."@ko .

bdc:producesProduct a owl:ObjectProperty ;
    rdfs:label   "produces product"@en, "제품 생산"@ko ;
    rdfs:comment "The FinishedGood that a WorkCenter produces."@en ;
    rdfs:domain  bdc:WorkCenter ;
    rdfs:range   bdc:FinishedGood .

Standard basis: OWL 2 Quick Reference §2.7 defines rdfs:label and rdfs:comment as built-in annotation properties. These are "standard annotations that can be attached to any class, property, or instance." Major ontologies such as FOAF, schema.org, and Dublin Core commonly attach them to T-Box definitions.

The practical convention differs slightly depending on where they are attached:

Where	label	comment
Class · relationship (ObjectProperty) (T-Box)	Nearly always — business name, verb phrase	Nearly always — concept description, LLM context
Instance (A-Box)	Nearly always — identifier or name (`"Z_ASM3"`)	Rarely — typically replaced by a dedicated datatype property

Comments on the A-Box are rare because facts about an instance are more useful as discrete datatype properties than as free-form prose. They are easier to validate and query. Rather than the free-form "Z_ASM3 is the bicycle final-assembly line," the same information is split into bdc:workCenterTypeCode "A" or similar.

Internationalization (i18n): language tags in a single property

rdfs:label and rdfs:comment accept RDF's language-tagged literals directly. Multiple language values can sit on the same property with @en / @ko and other language tags (as in the Turtle example above). With this in place, the Part 4 Agent retrieves the user's language with a single line FILTER(LANG(?label) = "ko") in SPARQL. Multilingual support is delivered through the ontology alone, with no backend code changes.

When users call the same entity by different names: skos:altLabel

One more situation comes up: when users refer to the same entity by different names. Calling a "공급사" a "벤더," or using "Vendor" instead of "Supplier." rdfs:label is a vocabulary for assigning one preferred name per entity, so packing synonyms into it is awkward. This is where the W3C SKOS (Simple Knowledge Organization System) standard's skos:altLabel fills the gap.

bdc:Supplier  a  owl:Class ;
    rdfs:label     "Supplier"@en, "공급사"@ko ;
    skos:altLabel  "Vendor"@en, "벤더"@ko, "거래처"@ko .

When the Agent encounters an expression such as "vendor USSU-VSF01..." in a user question, the skos:altLabel in the ontology links it to bdc:Supplier. If rdfs:label is the "official name," skos:altLabel holds "the other recognized names." The SAP domain mixes ABAP abbreviations (EKKO, KNA1) with business vocabulary (PurchaseOrder, Customer), so this pattern fits especially well.

How labels, comments, and altLabels are applied in bulk is covered in Section 6. Rather than typing each one by hand for dozens of classes, an LLM given the YAML and domain context fills them in consistently.

1. Preparing the Work Environment: BDC Connection, Users, Synonyms

With the vocabulary established, we can now prepare the implementation environment. Before substantive ontology work begins, the environment must be ready. Three pieces are required:

Source: Install an SAP BDC Data Product into HANA Cloud to obtain the Virtual Table and CSN metadata.
User & Permissions: A working user with catalog read, Virtual Table SELECT, and ownership of the working schema.
Synonym: A mapping that groups long Virtual Table names into short ones to make subsequent SQL queries and KG generation work easier.

ℹ️ About the .env file
The .env referenced throughout this post is a local-development environment variable file. It holds sensitive values, including HANA Cloud connection details (HANA_ADDRESS, HANA_PORT, HANA_USER, HANA_PASSWORD), SAP AI Core keys, AWS S3 keys, which the LLM references while writing code. It is required only for local testing; for production deployments, use a secret management service such as Kyma Secret.
All Vibe Coding prompts in this post assume .env is already configured.

ℹ️ About utils.py / get_hana_connection()
The utils.py referenced in the Vibe Coding prompts is a helper module that centralizes connections to external systems such as HANA Cloud, AI Core, S3. get_hana_connection() is the function that builds a HANA Cloud connection: it reads the .env connection details and returns an hdbcli connection object.
Because the LLM can call this single function instead of rewriting connection code each time, the resulting code is shorter and the only thing that needs to change when the environment shifts is .env. Copy our demo's utils.py into your project, or ask the LLM directly: "Create a utils.py with a get_hana_connection() function that reads .env and returns a HANA connection."

Source: connecting a BDC Data Product to HANA Cloud

📌 This section covers the hands-on setup that Part 1 Section6 introduced.
References. This series does not cover the detailed procedure from installing BDC Data Products into HANA Cloud and getting CSNs of them from SAP HANA Cloud Central as Part 1 already explained them. Please, check out the Part 1 and the the official SAP guides.
Tutorial: HANA Cloud Data Products Consumption
Official documentation: Data Product Support in SAP HANA Cloud
Here, you will find the steps: after download the CSN JSON files, where to put them and how to set up the HANA Cloud environment before ontology work begins.

Ontology design begins the moment an SAP BDC Data Product is shared into HANA Cloud. Select a Data Product in the BDC catalog and install it into HANA Cloud: a Virtual Table is created, and at the same time the CSN metadata (column names, types, FK associations, and so on) becomes available. With no separate script for extracting metadata, the raw material for ontology design is in place after a few clicks.

This metadata is the starting point for ontology design. When you write an ontology, you need to know precisely which entities, columns, and relationships exist, and which Competency Questions (business requirements) the ontology must address. The metadata addresses the first half.

📁 CSN metadata is gathered in the docs/dp_specs/ folder.
When you install each Data Product from BDC into HANA Cloud, you can download the CSN JSON file alongside it (from the BDC Catalog Data Product detail view, or the HANA Cloud Central Data Product tab). Place the downloaded files in your project's docs/dp_specs/ folder, and the LLM can reference them in bulk during the later Vibe Coding stages as docs/dp_specs/*_CSN.json.
docs/dp_specs/
  ├── WorkCenter_CSN.json
  ├── Product_CSN.json
  ├── Supplier_CSN.json
  ├── Customer_CSN.json
  └── ...
This folder becomes the shared input for Section 2 (CSN_SUMMARY authoring), Section 3 (KG / SQL classification), and Section 4 (Class Partition decisions).

For teams working directly with S/4HANA, as covered in Part 1 Section 1, CDS View definitions can serve as the same metadata raw material.

User & Permissions: a working user with catalog read access

To query installed Virtual Tables and use them for ontology work, a user with appropriate permissions is required. Rather than performing every operation as DBADMIN, it is cleaner to create a dedicated working user (for example, BDC_DP) and grant the following:

Read access to metadata views such as SYS.VIRTUAL_TABLES and PUBLIC.VIRTUAL_COLUMNS: for Virtual Table and column metadata exploration
SELECT on each BDC DP schema: for Virtual Table queries
Ownership of a working schema (for example, BDC_DP😞 where synonyms and KG helper Views will be created

💡 Our demo's 00_hana_setup.sql performs the same setup in one shot. It bundles user creation, BDC DP schema SELECT grants, system catalog read access, and working-schema creation into a single SQL script.

Synonym: shortening long Virtual Table names

This step is genuinely needed only after Section 3, once you have decided "which Data Products and which tables within them to place in the KG." It is sufficient to create synonyms only for the chosen tables. Still, because the flow "BDC connection → user setup → make SQL easier to write" reads naturally as one block, and because subsequent work flows more smoothly afterward, we cover it here in advance. Whether to define synonyms only for selected tables or for every Virtual Table brought from BDC is a matter of working style.

Immediately after installation, two names are auto-generated. A separate schema is created per Data Product, and the Virtual Table sits inside it:

DP schema name:
  _SAP_DATAPRODUCT_sap_s4com_dataProduct_WorkCenter_v1_<DP_GUID>

Virtual Table inside it:
  _SAP_DATAPRODUCT_<VT_GUID>_workcenter.WorkCenter

The schema itself is long, multiple DPs produce many schemas, and the table names inside each schema are long as well. Writing these out in every SQL statement is inefficient. Consolidating them into short synonyms in one place is the first step before substantive work begins.

CREATE SYNONYM BDC_DP.WORK_CENTER FOR
  "_SAP_DATAPRODUCT_<VT_GUID>_workcenter"."WorkCenter";

With this in place, subsequent SQL can use the short name BDC_DP.WORK_CENTER.

Vibe Coding: querying the Virtual Table list

📥Input
.env: HANA Cloud connection details (HANA_ADDRESS, HANA_PORT, HANA_USER, HANA_PASSWORD)
📤Output
virtual_tables.csv: full list of available BDC Virtual Tables (SCHEMA_NAME, TABLE_NAME)
Used in: Section 1 synonym creation, Section 2 CSN_SUMMARY authoring

This step is delegated to the LLM. The human reviewer's role is limited to confirming that the resulting CSV is produced correctly.

Make get_hana_connection() in utils.py read the HANA Cloud connection details
(HANA_ADDRESS, HANA_PORT, HANA_USER, HANA_PASSWORD) from .env and connect to
HANA Cloud.

Then use this function to query SCHEMA_NAME and TABLE_NAME from the
SYS.VIRTUAL_TABLES view, and save the result as virtual_tables.csv.

Use docs/dp_specs/virtual_tables_template.csv as the column structure reference (SCHEMA_NAME, TABLE_NAME — synonym columns will be added in the next step)

Vibe Coding: synonym creation

📥Input
virtual_tables.csv: the VT list from the previous step (SCHEMA_NAME, TABLE_NAME)
📤Output
ingestion/01_setup_synonyms.py: synonym creation script
Short-name synonyms created in HANA's BDC_DP schema (long SAP table names → short names)
virtual_tables.csv updated: enriched CSV with synonym_schema and synonym_name columns added
Used in: Section 2 CSN_SUMMARY authoring, Section 2 JOIN verification, the full Part 3 pipeline

The LLM examines the VT list, proposes short synonym names, and generates the code for creating them. The human reviewer confirms that there are no collisions (no existing synonym with the same name) and that the short names match the domain vocabulary, then runs the script in the local development environment. Once the names are recorded in the CSV, subsequent stages can carry the VT ↔ synonym mapping in a single file.

For each VT in virtual_tables.csv, propose a short synonym name (for example,
WORK_CENTER, SALES_ORDER_ITEM) and write the code that creates each synonym
under my working schema (BDC_DP) into ingestion/01_setup_synonyms.py.
Run it immediately after writing, and update virtual_tables.csv by adding
synonym_schema and synonym_name columns.
The final CSV should match the 4-column structure in docs/dp_specs/virtual_tables_template.csv (SCHEMA_NAME, TABLE_NAME, synonym_schema, synonym_name).

Section 1 deliverables

Step	Deliverable	Role
BDC → HANA install (manual)	`docs/dp_specs/*_CSN.json`	Input for Section 2 CSN_SUMMARY
User & Permissions (manual SQL)	Working user + working schema	Context for all subsequent SQL / synonym creation
Query VT list (Vibe Coding)	`virtual_tables.csv`	Input for synonym creation and CSN_SUMMARY VT matching
Create synonyms (Vibe Coding)	`01_setup_synonyms.py` + HANA synonyms + enriched `virtual_tables.csv`	Short names for SQL queries and later KG generation steps, the working environment for Sections 2–6

Section 1 ends here as environment preparation. The substantive question, "what to design on top of this data" (KG vs SQL classification, classes, relationships), begins at Section 2 with the CSN_SUMMARY and accumulates in dp_mapping.yaml.

2. Organizing Your Data as Ontology Material

With the environment ready, the actual ontology work begins. Authoring the CSN_SUMMARY, drafting dp_mapping.yaml, and verifying JOIN candidates for relationships fall within the scope of Section 2.

🎯 What you will build starting in Section 2: dp_mapping.yaml (the single source of truth for ontology work)
If Section 1 was environment setup, Section 2 starts the design decisions. The file in which those decisions accumulate is dp_mapping.yaml, and it is the single source of truth that collects every decision made across Sections 2–6. "Which DPs go into the KG, which entities become which classes, how to partition". All of these decisions converge in one file. The blank template is in ingestion/dp_mapping.template.yaml, and the final form follows a five-region structure:
# ingestion/dp_mapping.template.yaml (excerpt, summarized)
synonym_schema: &synonym_schema "BDC_DP"     # the synonym schema created in Section 1

# ─── Master Data: core node DPs that serve as endpoints of relationships (the start/end of CQs) ───
master_data:
  - name: <DP. e.g., WorkCenter>
    kg_class: <bdc:ClassName>
    description: "<one-line DP description>"
    virtual_table_schema: "_SAP_DATAPRODUCT_..._<DP>_v1_<DP_GUID>"
    entities:
      - entity: <entity name>
        synonym_schema: *synonym_schema
        synonym_name: "<SHORT_NAME>"
        virtual_table_name: "_SAP_DATAPRODUCT_<VT_GUID>_<dp>.<Entity>"
    # partition [Optional]: added for DPs that require Class Partition (Section 4 decision)
    partition:
      discriminator: <column>
      parent_class: <kg_class above>
      subclasses:
        - value: <column value>
          kg_class: <bdc:SubClass>

# ─── Structural Data [Optional]: multi-hop bridge / junction roles ───
# If master_data alone connects all relationships, this category can stay empty.
structural_data:
  - name: <DP>
    role: <multi-hop-intermediate | bridge-with-attributes>
    ...

# ─── Transaction Data: not loaded into the KG, used as SQL aggregation targets ───
transaction_data:
  - name: <DP>
    aggregation_columns: [<col1>, <col2>]
    ...

# ─── Relationships: ObjectProperty definitions + KGR View mapping (Section 5 decision) ───
relationships:
  - name: <relationship name, e.g., producesProduct>
    domain: <bdc:Class>
    range:  <bdc:Class>
    source:
      type: kgr_view
      view_name: <KGR_VIEW_NAME>
      sql_file: <path, e.g., ingestion/kgr_views/kgr_*.sql>
Because this YAML collects every decision in Sections 2–6, it appears repeatedly in the rest of this post. Following "where in the YAML each step's decision is recorded" gives a natural view of how the ontology comes together. For the full template and field descriptions, consult ingestion/dp_mapping.template.yaml directly.
One clarification: the YAML does not hold everything. The Turtle definitions of classes and properties themselves (including label and comment) are emitted in Section 6 as a separate ontology.ttl, and the SQL bodies of the KGR Views live in separate .sql files (the YAML's sql_file: points to the path). The YAML captures "which DP is classified where + where it comes from + how it is partitioned + which relationship is realized by which View." The semantics layered on top belong to the Turtle.

Organizing CSN metadata for ontology design

The design process starts with organizing the CSN (Core Schema Notation) metadata. The CSN specification for each BDC Data Product is available as JSON, but it contains every field and annotation. The full payload is too verbose to feed directly into ontology design.

So for each DP, the following information is distilled into a CSN_SUMMARY document:

Main entity name and ABAP source name
Key columns (PK + business key)
Relationship links (FK and similar): which column connects to which entity in which DP
Amount / quantity columns: fields that may become SQL aggregation targets
KG / SQL classification candidate: master data or transaction

This task can also be delegated to the LLM. Hand it the CSN JSON files and the blank template together and ask: "Organize each DP's main entity, keys, FKs, and amount columns into a table." A person reads the result and decides "this DP goes into the KG or SQL; this FK is a relationship candidate," and those decisions are persisted in the next step's dp_mapping.yaml.

📌 CSN_SUMMARY and dp_mapping.yaml have separate roles. CSN_SUMMARY is responsible for "a human-readable compression of raw CSN." The results of decisions, such as "DP category classification / multi-hop relationships / Class Partition / VT · synonym mapping" — belong in the next step's dp_mapping.yaml. Putting everything in a single document blurs the line between "compressed reference" and "decision," and any decision change requires editing two places.

Vibe Coding: authoring CSN_SUMMARY

📥Input
docs/dp_specs/*_CSN.json: per-DP CSN specs (downloaded alongside the BDC Data Product)
docs/dp_specs/CSN_SUMMARY_TEMPLATE.md: blank template (in the workshop materials, or the demo repository)
virtual_tables.csv (enriched): the Section 1 VT list + synonym information
📤Output
docs/dp_specs/CSN_SUMMARY.md: per-DP compressed reference filled in with domain data
Per DP: main entity / key columns / relationship links / amount · quantity columns / tentative KG · SQL classification
Used in: direct input for the Section 2 dp_mapping.yaml draft

This is the most important step in this post. The LLM reads all CSN JSON files and fills in the template. The domain expert's task is to review whether the classification and relationship candidates fit the domain.

Copy docs/dp_specs/CSN_SUMMARY_TEMPLATE.md to docs/dp_specs/CSN_SUMMARY.md
and fill in every <...> placeholder using these input sources:
- dp_specs/*_CSN.json: per-DP main entity, key columns, FKs, amount/quantity columns
- virtual_tables.csv (with synonym info): match each DP to its available VT

For each DP, fill in every section of the TEMPLATE:
- Main entity / ABAP source name / column count
- Key columns table
- Relationship links table (FKs and similar candidate connections to other DPs, raw)
- Amount/quantity columns table
- Tentative KG / SQL classification + one-line reason

⚠️ Follow the TEMPLATE's format (sections / table columns) exactly. Adjust the domain
   vocabulary to fit your data.
⚠️ Do NOT include comprehensive decisions such as "DP category / multi-hop relationships /
   Class Partition" here. Those belong in the next step's dp_mapping.yaml.

💡 Our demo's docs/dp_specs/CSN_SUMMARY.md is the result of this step. From it, a person can see at a glance which DPs are master data, which are transactions, and which relationships are feasible.

Moving CSN_SUMMARY into a `dp_mapping.yaml` draft

If CSN_SUMMARY was the "per-DP compressed reference" of what each DP looks like, dp_mapping.yaml is the SSoT in which comprehensive decisions are persisted based on it. Decisions intentionally left out of the CSN_SUMMARY, such as "DP category classification / relationship candidates / VT · synonym mapping", collect here. The same information is then ① classified by DP-level category (master / structural / transaction), ② grouped with each DP's VT / synonym information, and ③ given placeholders for downstream decisions (kg_class, multi-hop relationship definitions, and so on).

📌 CSN_SUMMARY → YAML mapping. The following moves from CSN_SUMMARY into the YAML:
Per-DP relationship links (FKs and similar) → the basis for tentative master_data placement (after Section 2 JOIN verification, some shift to structural_data)
Per-DP tentative KG / SQL classification → tentative category values in the YAML (in Section 3, some move to transaction_data)
VT / synonym mapping from the Section 1 enriched CSV → virtual_table_schema, virtual_table_name, synonym_name in the YAML
Amount / quantity columns → (not persisted in the YAML; the Part 4 SQL tool references CSN_SUMMARY directly)

Vibe Coding: drafting dp_mapping.yaml

📥Input
docs/dp_specs/CSN_SUMMARY.md: the per-DP compressed reference from Section 2
virtual_tables.csv (enriched): the Section 1 VT list + synonym information
ingestion/dp_mapping.template.yaml: blank template (in the workshop materials, or the demo repository)
📤Output
ingestion/dp_mapping.yaml draft: all DPs tentatively placed in the master_data category, with each DP's virtual_table_schema, entity list, and synonym_name filled in
Used in: Section 2 JOIN verification, Section 3 KG vs SQL classification, Section 4 Class Partition, Section 5 final Ontology

The LLM reads the CSN_SUMMARY and the enriched CSV and fills in the YAML skeleton. A person confirms only that the tentative category placement is correct and that the synonym names are persisted accurately.

Follow the structure of ingestion/dp_mapping.template.yaml exactly and produce
an ingestion/dp_mapping.yaml draft.

Input sources:
- docs/dp_specs/CSN_SUMMARY.md : per-DP main entity, keys, relationship links,
  amounts/quantities, tentative KG/SQL classification
- virtual_tables.csv (enriched) : VT list + synonym_schema, synonym_name

What to fill in:
- Place every DP tentatively in master_data (I will reclassify in later steps)
- Leave structural_data and transaction_data with their keys present and empty lists
- Leave relationships with its key and an empty list (I will fill in relationship
  definitions during ontology design)
- For each DP, fill in name / description / virtual_table_schema / entities[]
  - entities[*]: entity, synonym_schema, synonym_name, virtual_table_name
- Fill in kg_class from the CSN_SUMMARY tentative classification + domain common sense
  (for example, WorkCenter DP → bdc:WorkCenter)
- Fill in metadata such as ord_id and priority from CSN_SUMMARY or the BDC catalog

⚠️ Follow the TEMPLATE's key names, indentation, and category order exactly.
⚠️ Do NOT add a partition (Class Partition) block in this draft — I will add it to
   the relevant DPs during the Class Partition decision step.
⚠️ Do NOT add items inside relationships in this draft — I will fill them in during
   ontology design. Leave the key present and the list empty.
⚠️ Do NOT add datatype_properties for any DP in this draft — I will organize them
   during ontology design once the class hierarchy is finalized.

Finally, do not just author the YAML — verify it directly and report the result:
- Confirm that yaml.safe_load() parses successfully
- Confirm that every DP is placed in exactly one of the three categories
  (compare against the DP list in CSN_SUMMARY; nothing missing)
- Confirm that each DP's synonym_name matches the value in virtual_tables.csv
  (enriched)
- Confirm that entities[*].virtual_table_name is not empty
If verification is not clean, briefly explain what went wrong, fix the YAML, and
verify again.
This is the input for every subsequent step, so a defect here surfaces only much
later — validate it thoroughly at this stage.

`dp_mapping.yaml` evolves step by step

The draft above is not completed in one pass. Immediately after setup, every DP is placed in master_data (tentative classification), and the decisions made in the later half of Section 2 through Section 5 refine the YAML classification.

⚠️The YAML classifies at the DP level. "This DP leans toward a relationship-bridging role" is the coarse classification the YAML captures. The finer entity-level decisions, such as "this entity is a KG node, this entity is a bridge, this entity is ignored" — are addressed in detail in Section 4 (Class Partition) and Part 3 (KGR Views).

Point in time	YAML change	Result of which decision
Immediately after draft	All 9 DPs in `master_data` (tentative), `relationships` empty list	"Everything brought in for now"
After Section 2 JOIN verification	ProductionRouting, PurchasingSourceList → `structural_data` (optional category)	Discovered as bridge / junction roles
Section 3 KG vs SQL	SalesOrder, PurchaseOrder, BillingDocument, ProdOrderConfirmation → `transaction_data`	Decision: "not in the KG, SQL only"
Section 4 Class Partition	`partition` block added to the Product DP (FERT/HALB/ROH → FinishedGood/SemiFinished/RawMaterial)	"One DP, three classes"
Section 5 final Ontology	`relationships` filled with ObjectProperty definitions + KGR View mappings	Semantic relationships between classes confirmed
Section 6 Turtle authoring	YAML stops changing. ontology.ttl is generated from YAML + separate label/comment	Ready for loading

Keep this table in mind as you read Sections 2 (latter half) through 5, and "where in the YAML each decision is persisted" becomes apparent. At the end of each subsection, we briefly summarize the "YAML changes resulting from this step."

CSN relationship links (FKs and similar) are a starting point; bind business relationships on top and verify with actual JOINs

CSN metadata indicates "this column is the relationship link (FK) of that table" . However, that is only a starting point. The ontology does not end there. Domain analysis adds business relationships not present in CSN (for example, "which Products a WorkCenter produces," a relationship the domain requires but that is not directly expressed as a standard relationship link), and relationships that span different Data Products (for example, locatedAt between WorkCenter in the WorkCenter DP and Plant in the Plant DP) must be bound by a person. CSN reports only relationships within a single DP; cross-DP relationships are filled in with domain knowledge. Whether a relationship comes from CSN, spans DPs, or is a business relationship, whether the JOIN actually works on real data must be verified separately.

This post follows R2RML principles when defining and verifying relationships. Regardless of whether the relationship is declared in CSN, as long as the values exist and a domain expert designates it a relationship, it becomes one. For the detailed R2RML standard, consult Part 2-1 Section 3.

It is common for metadata to declare a relationship while the data is missing, or for data types to mismatch subtly, or for one side's column to have so many NULLs that the relationship is effectively broken. Missing this during ontology authoring leads to "the relationship was declared, yet SPARQL returns zero rows" after loading.

The verification approach: execute the actual JOINs for both CSN's FK candidates and the business relationship candidates we added, and check the result row counts. If the result is 0 or far fewer than expected, that relationship is dropped from the ontology, or the data source must be revisited.

💡Our demo's ingestion/02_verify_joins.py performs this work. It collects the JOIN candidates (as SQL JOIN statements) within the script, executes them one by one, and prints the matching row counts. This script revealed that every row of ProductionRoutingHeader.WorkCenterInternalID in our demo data was '00000000', breaking the routing connection (the full case is in Part 5 Challenge 2), and triggered a redesign of the multi-hop path in the ontology.

This verification is repeated every time a new relationship is added to the ontology. The verification work becomes the foundation for the data pipeline in the next post (Part 3). Only verified relationships are persisted as ObjectProperties in the ontology, and the resulting KG actually works.

📌 This verification report is the basis for the decisions in Sections 3–5. Section 3's KG vs SQL classification, Section 4's Class Partition, and Section 5's final ontology structure, all are decisions made after confirming "which relationships are alive in the real data." Without verification, guessing at the ontology leads to SPARQL returning zero rows after loading.

📒 YAML changes from this step + one domain decision.
JOIN verification revealed two DPs that play "relationship / edge roles." ProductionRouting (a multi-hop intermediate between WorkCenter and Product) and PurchasingSourceList (a Supplier ↔ Product bridge). Both move from master_data to structural_data. One more decision is needed: how to handle multi-hop bridges in the KG.
Two paths when encountering a multi-hop bridge:
Option How the bridge is handled Pros Cons
(a) Direct connect (flatten) The bridge entity is not persisted in the KG; only the endpoints (A → C) are connected as a 1-hop relationship The KG stays clean, multi-hop does not pollute visualization, SPARQL is simple Information carried by the bridge itself is invisible in the KG
(b) Persist the bridge as a node The bridge entity is loaded into the KG as a separate class (A → B → C) The bridge's attributes (plant, period, priority) become explorable via SPARQL Node count increases, intermediate nodes appear in visualizations
We chose different answers for the two DPs.
ProductionRouting → (a) flatten. The routing header / operations themselves carry no attributes worth querying via SPARQL beyond the fact that "this WorkCenter produces this Product." A SQL View that compresses 4-hop into 1-hop (covered in Part 3) is created, and no nodes are loaded into the KG.
PurchasingSourceList → (b) persist as a node. PSL carries information of its own, such as plant, validity period, and priority beyond the basic "this supplier provides this material." Answering questions such as "show only priority-1 sources" requires PSL to be a node.
Both DPs go into the structural_data category because both serve "a supporting role connecting the core nodes in master_data." Within that category, whether a node is persisted in the KG (b) depends on whether the domain wants to ask further questions of that bridge. The fate of each is depicted concretely in Section 5 (final Ontology).
structural_data is an optional category that may be left empty depending on the scenario. If the core nodes in master_data alone connect every relationship, there is no need for it. We separated it as its own category because multi-hop is in play and a junction with its own attributes (PSL) is present.

Vibe Coding: the JOIN verification script

📥Input
ingestion/02_verify_joins.py (workshop materials / demo repository): the infrastructure code + JOINS / SAMPLE_QUERIES structure as a reference. Hand the LLM the file and say "following the structure and output format, fill in the JOINS for our domain only."
ingestion/dp_mapping.yaml: synonym mapping (BDC_DP.* short names)
docs/dp_specs/CSN_SUMMARY.md: relationship candidates + KG / SQL classification
Competency Questions (CQs): the business questions the KG must answer
📤Output
ingestion/02_verify_joins.py: a verification script populated with your domain's JOIN candidates
Verification report: per-candidate row count and match rate (execution stdout / log)
Used in: the basis for Section 3 KG vs SQL classification, Section 4 Class Partition, and Section 5 final ontology decisions

The verification script mixes work requiring domain knowledge ("is this relationship business-meaningful") with mechanical repetition ("count the rows of this JOIN"). Delegating the latter to the LLM lets a person focus exclusively on the former. The prompt should contain four elements:

Specify the metadata source. Tell the LLM where to find candidates. Point it at the SYS.VIRTUAL_TABLES / PUBLIC.VIRTUAL_COLUMNS metadata views, and hand it dp_mapping.yaml (the VT → synonym mapping) so it writes SQL with short names (BDC_DP.WORK_CENTER). Without the YAML, the LLM guesses long VT names and fails.
Provide the Competency Questions (CQs). Hand over "the questions the KG must answer" so the LLM can narrow the candidates by "which relationship resolves this question" (for example, "who is affected by a WorkCenter shutdown?" → the WorkCenter ↔ Product ↔ SalesOrder ↔ Customer chain becomes the verification target).
Concrete verification criteria. Replace vague language such as "works well" with numeric thresholds: row counts, NULL ratios, minimum matching thresholds.
Human-reviewable output format. Tabular format + sample rows. "What you can see with your eyes" becomes the input for the domain decision.

Good prompt:

"Following the structure and output format of ingestion/02_verify_joins.py
exactly, rewrite ingestion/02_verify_joins.py for our domain. Replace only
the JOINS and SAMPLE_QUERIES lists; do NOT modify the infrastructure
functions (run_join_checks, run_sample_queries, main).

[Input materials / attach together]
- 02_verify_joins.py (existing) : structure and output format reference
- dp_mapping.yaml                : VT → synonym mapping (BDC_DP.* short names)
- (if needed) CSN_SUMMARY.md     : relationship candidates (per-DP reference)

Competency Questions the KG must answer:
- CQ1: When a specific WorkCenter goes down, which customers' revenue is affected?
- CQ2: Which Product is produced at which Plant?
- CQ3: Which Supplier supplies which Product?
... (as many as needed)

First organize which relationship chains are needed to answer these CQs, and
on top of those chains, populate the JOINS list with three kinds of
candidates:

(a) Direct relationship links within one DP : identify candidates by column
    name patterns (for example, '*ID', '*Code')
(b) Relationships across DPs                 : the same column name or the
    same domain values appearing in multiple DPs
(c) Multi-hop business relationships         : chains added through domain
    analysis (I will provide the JOIN SQL separately)

Write SQL with the short synonym names in dp_mapping.yaml (BDC_DP.WORK_CENTER
and similar). Place each entry in the same tuple form as the existing file
(label, key columns description, SQL).

Additionally, populate SAMPLE_QUERIES with 3–5 spot-check queries that a person
can verify by eye (for example, 'top 10 WorkCenters', 'sample 5 rows joined
via a specific relationship').

Finally, do not just author the script — execute it and show me the results.
- If every JOIN matches with ✅, you are done.
- If any item returns ⚠️ 0 rows or ⛔ an error, briefly hypothesize the cause
  (wrong column name? missing data? a different path needed?) and propose a
  fix. Once I approve, modify JOINS and re-run. Repeat until the result is
  clean.

[After verification passes, persist candidates to the YAML]
Once verification is clean, persist the surviving JOINs into the relationships
section of dp_mapping.yaml as 'free-form candidates.' Do not yet populate the
formal ObjectProperty form (name/domain/range/source) — I will organize that
during ontology design.

Example (one item each, free-form description only):
relationships:
  - description: "WorkCenter → ProductionRoutingOpSubord (key: WorkCenterInternalID+TypeCode, matched: 8,432 rows)"
  - description: "Product → ProductPlant via Material (matched: 3,197 rows)"
  - ...

⚠️ Do NOT touch master_data / structural_data / transaction_data / partition /
   datatype_properties.
⚠️ After modifying the YAML, confirm yaml.safe_load() parses successfully."

→ Once the LLM organizes "which relationship chains are needed to answer the CQs" and writes the verification script, a person reads the results and decides "keep this relationship, drop that one." Our demo's 02_verify_joins.py was built exactly this way, so handing that file as a reference lets the LLM fill in JOINs for your own domain in the same structure and format.

Bad prompt:

"Verify that the FKs work properly."
→ "Properly" has no criterion. The LLM looks at the metadata only and says "FK
   is declared, so OK."
→ Without the CQs the KG must answer, no way to distinguish important
   relationships.
→ Without the synonym list, the LLM guesses long VT names or writes generic SQL.
→ Cross-DP and multi-hop relationships are out of sight entirely.

Roles:

LLM: drafting dp_mapping.yaml + step-by-step updates (moving DPs between master_data / structural_data / transaction_data based on verification results, filling in kg_class), writing catalog query SQL, deriving relationship chains from the CQs, writing JOIN execution scripts, organizing result tables, flagging clearly broken relationships (zero matches)
Domain expert: ① defining CQs (the list of business questions the KG must answer), ② reviewing whether the LLM's proposed YAML classification and naming match the domain vocabulary, ③ deciding which relationship candidates to add to the verification target (especially cross-DP and multi-hop), ④ judging whether to keep or drop relationships with low match rates, ⑤ analyzing whether broken relationships are due to missing data or whether they can be routed differently

Section 2 deliverables:

Step Deliverable Role	Step Deliverable	Role
CSN_SUMMARY authoring	`docs/dp_specs/CSN_SUMMARY.md`	Per-DP main entity / keys / relationship links (FKs and similar) / amounts · quantities (compressed per DP)
`dp_mapping.yaml` draft	`ingestion/dp_mapping.yaml`	SSoT draft with category classification, VT / synonym mapping, and `kg_class` placeholders filled in
JOIN verification script	`ingestion/02_verify_joins.py` + verification report	Match rate and NULL ratio per relationship candidate, the basis for decisions in Sections 3–5

3. Deciding Between KG and SQL

After working through Section 2, the categorization in dp_mapping.yaml is refined once. Core node DPs are in master_data, DPs that emerged as bridges are in structural_data, and the transaction_data slot is still empty.

This section makes two decisions:

Section 3.1: transactional data (numeric aggregation targets) go to SQL, moving to transaction_data
Section 3.2: master data orphaned by those moves (entities that became "islands" in the KG) also go to SQL

After these two decisions, only "master data whose structural relationships must be traversed" remains in the KG.

Entities whose structural relationships must be traversed → KG. Data that must be aggregated numerically → SQL. Entities that are not connected to other nodes within the KG → SQL.

Our final classification (instance counts below are SAP demo data examples):

KG (master data, structural relationships):
├── WorkCenter   , work center (129 examples)
├── Product      , finished / semi-finished / raw material (2,593 examples)
├── Supplier     , supplier (153 examples)
├── Plant        , plant (12 examples)
└── PurchasingSourceList  ← Supplier ↔ Product bridge node

SQL (transactional, numeric):
├── SalesOrder / SalesOrderItem
├── PurchaseOrder / PurchaseOrderItem
├── BillingDocument / BillingDocumentItem
└── ProdOrderConfirmation

SQL (master orphaned as an island, lookup only):
└── Customer → name / country lookup via SQL CUSTOMER synonym

The W3C standards do not make this decision. The standard only says "create reference triples when FKs exist." "Should this entity live in the KG?" is a domain judgment.

3.1 Transactional data goes to SQL

The first decision is clear. "Data whose core is dates, amounts, and counts" does not belong in the KG.

Reasons not to load it into the KG:

Instance explosion: transactions are voluminous and change frequently. SalesOrder alone runs into tens or hundreds of thousands of rows. Graph nodes increase in proportion, weighing down both visualization and SPARQL query cost.
Numbers are natural in SQL: aggregations such as "revenue per customer" are much simpler and faster with SQL GROUP BY than with SPARQL.
Not a KG question: the KG exists to answer "what does this WorkCenter produce?" style structural traversals, not "what is the total?"

In our scenario, four DPs match these criteria:

DP	Why it is transactional
`SalesOrder` / `SalesOrderItem`	Sale date · amount · per-customer orders
`PurchaseOrder` / `PurchaseOrderItem`	Purchase date · amount · per-supplier orders
`BillingDocument` / `BillingDocumentItem`	Billing date · amount
`ProductionOrderConfirmation`	Production completion date · quantity

These four DPs move from master_data to transaction_data. The actual YAML update is handled together with the Section 3.2 island candidate check via a single Vibe Coding session at the end of Section 3.

📒 YAML changes from this step: the four DPs above move from master_data to transaction_data, and each DP's aggregation_columns is populated. Their entities are not persisted as KG nodes; they are used only as SQL aggregation targets. They remain in the YAML because the synonyms themselves are still needed for SQL queries (classification differs, but the synonyms persist).

3.2 Then master data that became an island also goes to SQL

After removing the transactional DPs in Section 3.1, looking again at the KG reveals an unexpected side effect. A piece of master data has become "an island."

In our scenario, Customer did. Customer is master data, and the demo data has roughly 215 instances. Initially, we naturally intended to place it in the KG. "Customers who buy Products" is a core relationship in the scenario.

But there was a problem. The bridge connecting Product and Customer is SalesOrder, and we removed SalesOrder from the KG in Section 3.1. The KG then looks like this:

With the bridge (SalesOrder) absent from the KG, the KG path from Product to Customer is severed. Even if Customer is persisted in the KG, it is an isolated island unconnected to other nodes. The Agent cannot navigate outward from a Customer instance via SPARQL, and other KG nodes cannot reach Customer. Roughly 200 instances would remain as an isolated collection of nodes.

So we decided to "handle the Product → Customer connection in SQL" (since SalesOrder is already in SQL, one SQL JOIN on SALES_ORDER_ITEM.Material / SoldToParty suffices), and moved Customer itself to a SQL lookup. Looking up name and country by ID is all that is required.

Even for master data, if it is not connected to other nodes within the KG, there is little reason to place it there. For simple lookup, SQL is simpler.

"Island candidate" signals

To make the same judgment in your own domain, the master data that will become "an island" becomes visible only after working through Section 3.1. Two signals:

Is the bridge transactional, so it moved to SQL? If the only path connecting this master to other masters lies inside a transactional DP that moved to SQL in Section 3.1, placing it in the KG produces a disconnected node. (The DPs the LLM reports as "island candidates" at the end of the Section 3.1 Vibe Coding fall here.)
Is lookup sufficient? If there is no "navigating outward" from this master to other entities via SPARQL (only looking up names and attributes by ID), a SQL lookup is simpler.

When both apply, moving to SQL is the natural choice.

⚠️ Limits of island detection: at design time, candidates only; final confirmation comes after running the Agent. The Section 3.1 Vibe Coding catches the structural signal "the bridge moved to SQL" automatically, but the usage signal "SPARQL never actually starts here" surfaces only after running the Agent. We too initially placed Customer in the KG, then after running the Z_ASM3 scenario and confirming that "it was never used as a starting point," moved it to SQL. The detailed case is covered in Part 5 Challenge.

📒 YAML changes from this step: masters confirmed as islands among the "island candidates" reported in Section 3.1 (in our case, Customer) drop out of the KG node set. They remain in the master_data category in the YAML, but they are not loaded as KG classes when authoring the Section 5 final ontology Turtle.

Vibe Coding: handling Section 3 in one shot (transaction classification + island candidate reporting)

The decisions of Section 3.1 and Section 3.2 are handled together in a single LLM prompt. Immediately after classifying transactional DPs, ask the LLM to check whether "any master data depended on a bridge that was just moved to transactional," and the Section 3.2 review goes much faster.

📥Input
ingestion/dp_mapping.yaml (updated through Section 2 — master_data + structural_data)
docs/dp_specs/CSN_SUMMARY.md (per-DP amount and quantity columns documented)
CQ list
📤Output
ingestion/dp_mapping.yaml updated: transactional DPs moved to transaction_data + each DP's aggregation_columns populated
Island candidate report: the list of master DPs (if any) disconnected from the KG as a result of the transactional moves

Examine ingestion/dp_mapping.yaml, docs/dp_specs/CSN_SUMMARY.md, and the CQ
list, and pick the "DPs that should be classified as transactional," moving
them into the transaction_data category.

Transaction criteria:
- DPs whose core is dates, amounts, and counts (consult the amount/quantity
  columns in CSN_SUMMARY)
- High volume, frequently changing (SalesOrder, PurchaseOrder, BillingDocument
  and similar)
- Appear in the CQs in "total / average / aggregation" form (numeric
  aggregation rather than structural traversal)

When moving:
- For each DP, populate aggregation_columns with the amount/quantity columns
  from CSN_SUMMARY
- Do NOT touch the master_data / structural_data classification (decided in
  earlier steps)

⚠️ Important: after moving transactional DPs, examine master_data once more.
If a master DP's only path to other master nodes ran through a transactional
DP that was just moved, that master will become an "island" in the KG.
If such a candidate exists, report it separately as a "KG island candidate"
(leave the YAML category as master_data for now — I will move it after
confirmation).

Finally:
- Which DPs moved to transaction_data + what aggregation_columns were populated
- If there are island candidates, which DP is suspected and why (which
  transactional DP was the bridge)
Summarize briefly and show me.

⚠️ After modifying the YAML, always confirm yaml.safe_load() parses
successfully, and if it breaks, briefly explain what went wrong, fix it,
and verify again.

A person reviews the LLM's "island candidates" and confirms which ones to remove from the KG node set (the YAML category stays as master_data; the entity simply is not persisted as an ontology class in Section 5).

Section 3 deliverables:

Step	Deliverable	Role
Transactional → SQL (Section 3.1)	`dp_mapping.yaml` update (4 DPs to `transaction_data`)	SQL aggregation targets confirmed
Islands → SQL (Section 3.2)	`dp_mapping.yaml` update (island candidate entities excluded from KG nodes)	Entities for the KG and entities for SQL-only confirmed

4. Splitting One Data Product into Multiple Classes (Class Partition)

After the KG vs SQL classification, the next frequently encountered domain decision is Class Partition.

SAP BDC has a single Product Data Product. HANA Cloud has a single corresponding Virtual Table (BDC_DP.PRODUCT). Inside that table are finished goods, semi-finished goods, and raw materials. The distinguishing field is MaterialType.

SELECT "MaterialType", COUNT(*) AS cnt
FROM BDC_DP.PRODUCT
GROUP BY "MaterialType"
ORDER BY cnt DESC;

MaterialType	SAP meaning
`HALB`	Semi-finished (Halbfabrikat)
`FERT`	Finished good (Fertigprodukt)
`ROH`	Raw material (Rohmaterial)

Applied as-is, W3C Direct Mapping would map all three to a single bdc:Product. The data is stored. But we split it into three classes for two reasons.

Reason 1: the directionality of relationships differs

In a supply chain BOM, the flow is always one-directional.

WorkCenter ──producesProduct──▶ FinishedGood
FinishedGood ──hasComponent──▶ SemiFinished
SemiFinished ──hasComponent──▶ RawMaterial

If all three are bdc:Product, a SPARQL query for "what does Z_ASM3 produce?" may return a mix of raw materials and semi-finished goods. Type constraints enforce the correct answer.

Reason 2: an LLM reasons from class names

When the Agent sees ?p a bdc:FinishedGood in a SPARQL result, it knows immediately: this is a sellable end product, so look at sales orders and customers. For bdc:RawMaterial, look at procurement, suppliers, and purchase orders. The class name conveys business meaning, and the LLM uses that meaning to decide its next action.

The Class Partition pattern

In ontology design, this situation is called Class Partition or Discriminator-based Class Assignment. The pattern assigns different KG classes to rows of a single source (table) based on the value of a specific column (discriminator).

In OWL, this disjointness between classes can be declared explicitly.

# The three classes are mutually disjoint (a finished good cannot also be a raw material)
bdc:FinishedGood  owl:disjointWith bdc:SemiFinished .
bdc:FinishedGood  owl:disjointWith bdc:RawMaterial .
bdc:SemiFinished  owl:disjointWith bdc:RawMaterial .

# Or, with owl:disjointUnion (the three classes form a complete partition of Product)
bdc:Product owl:disjointUnion (bdc:FinishedGood bdc:SemiFinished bdc:RawMaterial) .

Signals that Class Partition should be considered

While exploring a Virtual Table, if any of these patterns appears, consider partitioning:

A type / category column exists: MaterialType, DocumentType, OrderType, and so on
Different row sets connect to different entities: some rows link to Supplier, others to Customer
Business users say "those are different things": "finished goods and raw materials are different."

This pattern appears often in BDC Data Products because S/4HANA table design relies on type columns for flexibility, storing multiple concepts in a single table. ODM surfaces these as meaningful names, but whether to split them into KG classes is the designer's decision.

Design rule: if different row sets participate in different relationships, split a single source table into multiple KG classes.

The Class Partition decision is made by a person

Do not delegate "split this table into classes" to the LLM wholesale. The LLM does not know the business meaning and will partition the wrong place, or merge a place that should be partitioned. Which of the three signals above (type column · different relationships per row set · business users distinguishing them) applies to your domain is something only a person knows.

Vibe Coding: Class Partition (two steps)

📥Input
ingestion/dp_mapping.yaml: DP list under review + synonym (BDC_DP.<NAME>) and virtual_table_schema / name mapping
docs/dp_specs/CSN_SUMMARY.md: per-DP keys / relationship links / amount · quantity columns (supplementary)
HANA Cloud's PUBLIC.VIRTUAL_COLUMNS (column metadata) + BDC_DP.<SHORT_NAME> (row queries)
📤Output
Step 1: partition candidate table (DP · column · distinct values · row counts · expected connections) + first-pass recommendation
Step 2: partition block added to the relevant DP in dp_mapping.yaml (discriminator + subclass mapping)
In the next step (Section 6), when authoring ontology.ttl, this partition information is converted into Turtle class definitions

Good prompt / Step 1: find partition candidates

"For the DPs in the master_data and structural_data categories of
dp_mapping.yaml, organize type/category partition candidates.

[Input materials]
- ingestion/dp_mapping.yaml : DP list under review + synonym / VT name mapping
- docs/dp_specs/CSN_SUMMARY.md : supplementary — per-DP keys / relationship
  links / amount · quantity columns

Each DP entity has two names in the YAML, each with a different purpose:
- synonym (for example, BDC_DP.WORK_CENTER) : short name for SQL row/value queries
- virtual_table_schema + virtual_table_name : original names for catalog queries
  ⚠️ HANA Cloud has no DESCRIBE. Column information must be queried from
  PUBLIC.VIRTUAL_COLUMNS using virtual_table_schema/virtual_table_name (not
  the synonym).

What to organize (automatable):
1. The column list for each entity (query PUBLIC.VIRTUAL_COLUMNS)
2. Candidate columns that look like a type/category (MaterialType, DocumentType,
   OrderType, and so on)
3. For each candidate column, the distinct values + per-value row counts
   (SELECT <candidate>, COUNT(*) FROM BDC_DP.<SHORT_NAME> GROUP BY <candidate>
    — using the synonym)
4. For each distinct value, guess which other DP/column it likely connects to,
   and run a light feasibility check
   - The guess is based on column names and domain common sense (for example,
     MaterialType='FERT' → SalesOrderItem.Material likely)
   - Confirm only by comparing distinct counts on both columns. Do not run JOINs.
     If the distinct values on both columns overlap, report "likely connection."

Show the result as a table:
DP | candidate column | distinct values | per-value row count | expected
   connected DP·column | expected column's distinct count (+overlap signal).

After the table, add a single paragraph with a first-pass recommendation:
"Partitioning looks worthwhile for candidates X and Y. Reasons:
- X: all N distinct values look meaningful, per-value row counts are balanced,
  and the connected DPs differ by value (overlap pattern varies by value)
- Y: ...
Conversely, A and B look weak (for example, a single value covers 99%+, or
distinct count is too high suggesting an ID rather than a type column, or
every value has only 1–2 rows so domain meaning is weak)."

⚠️ SQL usage limit: stop at distinct + COUNT. Do not run JOINs.
- JOINs are not needed to find partition candidates (distinct comparison on
  both sides is enough)
- BDC Virtual Tables are external system calls, so heavy JOINs are costly."

→ Once the LLM produces the table and first-pass recommendation, the next stage is manual review by a person.

Manual review: do the type values play different business roles?

The LLM output above (column · distinct values · row counts · expected connections) shows only "the shape of a partition candidate." Judging the real partition value requires one more step.

The core question: does each type value play "a different business role"? There are two ways to look at this.

Cross-reference distinct + COUNT results (light, default): examine the "expected connected DP · column" and "expected column's distinct count (+overlap signal)" in the LLM table, and check whether the connections differ per type value. Since this is based only on distinct and COUNT, it is light, and the BDC Virtual Table cost is small.
Precise check with JOINs (only when needed): only when distinct · COUNT comparison cannot reveal the difference. For example, "both columns are 4-character codes with similar distinct counts; I want the actual matching row count" or "one side has trailing spaces, so distinct counts look identical but the JOIN match rate may be low." In these cases, use a verification script such as 02_verify_joins.py to confirm match rates and NULL ratios directly.

Example: examining the MaterialType candidate of the Product DP

MaterialType	How it is referenced in other DPs	Business role
`FERT` (finished good)	Large distinct overlap with `SalesOrderItem.Material`	Sold
`ROH` (raw material)	Large distinct overlap with `PurchaseOrderItem.Material` / `PurchasingSourceList.Material`	Purchased
`HALB` (semi-finished)	Appears in `Product.hasComponent` (internal BOM)	Internal assembly

If the three values show different connection patterns → different business roles → partition is worthwhile. If the three values show the same connection pattern → effectively the same role → partition value is weak, a single class suffices.

This judgment cannot be made by the LLM. With the LLM result table in hand, a person decides "are these type values really different roles?" Our scenario's Product followed exactly this analysis and led to the decision "three roles are clearly different → split into three classes."

Good prompt / Step 2: persist the decision as a YAML partition

"Take the Step 1 results and the partition decision I confirmed, and add a
partition block to the relevant DP in dp_mapping.yaml.

Confirmed partition (example):
- DP: BDC_DP.PRODUCT
- discriminator column: MaterialType
- value → class mapping:
    HALB → bdc:SemiFinished
    FERT → bdc:FinishedGood
    ROH  → bdc:RawMaterial

Deliverable: partition block added to dp_mapping.yaml
- A partition block at the same level as the relevant DP entity (per the
  template):
    - name: Product
      kg_class: bdc:Product
      entities:
        - entity: Product
          synonym_name: PRODUCT
          ...
      partition:
        discriminator: MaterialType
        parent_class: bdc:Product
        disjoint: true
        subclasses:
          - value: FERT
            kg_class: bdc:FinishedGood
            description: "Finished good"
          - value: HALB
            kg_class: bdc:SemiFinished
            description: "Semi-finished"
          - value: ROH
            kg_class: bdc:RawMaterial
            description: "Raw material"
- Output form: show the updated DP block as it should appear in the current YAML

⚠️ Do NOT create Turtle class definitions (rdfs:label, rdfs:comment,
rdfs:subClassOf, owl:disjointWith) in this step. The ontology.ttl authoring
step will take the YAML partition as input and generate them in one pass.

⚠️ In this step, persist only the partition block. Do not touch other regions
of master_data (entities, datatype_properties), structural_data,
transaction_data, or relationships. In particular, datatype_properties will
be organized separately in the next step.

[Memo for relationships narrowed by the partition (if any)]
If the partition result allows the range/domain of an existing relationship
candidate to be narrowed (for example, the range of producesProduct can be
refined from bdc:Product to the partition subclass bdc:FinishedGood), add
that information as a free-form description memo to the relationships
section of the YAML. Use the same tone (one-line description) as other
candidates already persisted there. Formal definitions will come in the
ontology design step.

Example:
relationships:
  - description: "WorkCenter → Product via routing chain (matched: 9,200 rows)"  # JOIN verification candidate
  - description: "[partition memo] The range of producesProduct from WorkCenter can be narrowed to bdc:FinishedGood (Product partition result)"  # partition memo

If no new relationship memos arise from the partition, skip this step.

⚠️ After modifying the YAML, always confirm yaml.safe_load() parses
successfully, and if it breaks, briefly explain what went wrong, fix it,
and verify again."

Bad prompt:

"Split the classes in this ontology appropriately."
→ "Appropriately" has no criterion. The LLM partitions by guesswork.
→ Information-carrying nodes such as BOMItem get oversimplified, losing
   information.

Roles:

Domain expert: decides whether to partition, which column acts as the discriminator, and which class names to use
LLM: identifying candidates from metadata (Step 1), persisting the decision as a YAML partition block (Step 2)

📒 YAML changes from this step: a partition block is added to the relevant DP entry. The existing kg_class (parent class, for example bdc:Product) stays, and the discriminator column, the subclass mapping, and the disjoint flag are added. The Turtle class definitions themselves are generated when authoring ontology.ttl in the next step, reading this YAML.

Section 4 deliverables:

Step	Deliverable	Role
Class Partition decision	`dp_mapping.yaml` update (discriminator partition rules + per-entity `kg_class`)	Input for Section 6 ontology Turtle authoring

5. Completing the Ontology

The KG ontology structure that emerges after applying every decision in Sections 3 and 4 is below. This structure is consistent with the final classification in dp_mapping.yaml. master_data becomes the bdc:MasterData hierarchy, PSL (the structural item with its own attributes) sits under bdc:StructuralNode, and DPs that act only as intermediate bridges, such as ProductionRouting, have no KG nodes and serve only as KGR View inputs (Part 3). If the YAML was the working log, the ontology TTL is the result of translating that log into W3C standard syntax.

Instance counts below are SAP demo data examples.

rdfs:Class
├── bdc:MasterData
│   ├── bdc:FinishedGood     , finished good (225 examples)
│   ├── bdc:SemiFinished     , semi-finished (2,185 examples)
│   ├── bdc:RawMaterial      , raw material (183 examples)
│   ├── bdc:Supplier         , supplier (153 examples)
│   ├── bdc:Plant            , plant (12 examples)
│   └── bdc:WorkCenter       , work center (129 examples)
│
└── bdc:StructuralNode
    └── bdc:PurchasingSourceList , Supplier ↔ Product bridge (16 examples)

Relationships:

WorkCenter   ──bdc:locatedAt──▶         Plant
WorkCenter   ──bdc:producesProduct──▶   FinishedGood
Product      ──bdc:locatedAt──▶         Plant
Product      ──bdc:hasComponent──▶      Product
PSL          ──bdc:forProduct──▶        Product
PSL          ──bdc:fromSupplier──▶      Supplier

PurchasingSourceList (PSL) is intentionally classified as StructuralNode rather than MasterData. PSL is not a simple N:N connection; it carries information such as "at which plant, for which validity period, with which priority." The decision was to keep meaningful junctions as graph nodes rather than flattening them.

📌 These relationships are realized as KGR Views in Part 3. bdc:producesProduct, which requires compressing a multi-hop chain; bdc:hasComponent, which traverses a BOM; bdc:locatedAt, a simple direct FK. Each is precomputed as a SQL View (KGR_*) that becomes input to instance TTL generation. The View patterns are covered in detail in Part 3 Section 3.

Vibe Coding: organizing `relationships` in the YAML

After Section 2 JOIN verification and Section 4 Class Partition, free-form description memos for candidates have accumulated in the relationships section of the YAML. In this step, those are organized in one pass into the formal ObjectProperty form (name / domain / range / source).

📥Input
ingestion/dp_mapping.yaml: the relationships section with Section 2 JOIN verification candidates + Section 4 partition memos accumulated as free-form descriptions, plus the master_data / structural_data / partition regions
The Section 5 ontology diagram above (the confirmed relationship list — which relationships to keep or drop, and what to call them)
The verification results from ingestion/02_verify_joins.py (per-candidate JOIN pattern and matching row count) — the basis for authoring SQL View bodies
📤Output
ingestion/dp_mapping.yaml update: free-form items in relationships replaced with the formal form (name / domain / range / source)
ingestion/kgr_views/<view_name lowercase>.sql files — the View body for each relationship (only the SELECT portion of CREATE VIEW)
Change description (which free-form candidate became which formal relationship)

Organize the relationships section of ingestion/dp_mapping.yaml.

Free-form description candidates persisted in earlier steps (JOIN verification +
Class Partition) have accumulated there. In this step, replace them in one pass
with the formal ObjectProperty form.

The ontology diagram I confirmed (relationship list):
- WorkCenter → bdc:locatedAt → Plant
- WorkCenter → bdc:producesProduct → bdc:FinishedGood  (※ range narrowed by partition)
- Product → bdc:locatedAt → Plant
- Product → bdc:hasComponent → Product
- PurchasingSourceList → bdc:forProduct → Product
- PurchasingSourceList → bdc:fromSupplier → Supplier
... (adjust to your domain)

Workflow:
1. Read every free-form description candidate in yaml relationships and match
   each to the confirmed list above. (Which candidate maps to which relationship.)
2. Replace relationships in the confirmed list with the formal form:
   - name : relationship name (camelCase)
   - domain : subject class
   - range : object class (use the narrowed subclass if a partition memo exists)
   - description : one-line description
   - source.type : kgr_view
   - source.view_name : convention KGR_<SUBJ>_<REL>_<OBJ>
   - source.sql_file : convention ingestion/kgr_views/<view_name lowercase>.sql
3. Remove free-form candidates that are not in the confirmed list. (Verified
   but decided against persisting in the ontology.)
4. For each formal relationship, author the actual SQL View body at the
   source.sql_file path:
   - Use the JOIN pattern from 02_verify_joins.py verification results
   - The file contains only the SELECT portion of CREATE VIEW (the 03 script
     wraps the CREATE VIEW statement)
   - Output columns: (subject_iri, object_iri) only. For multi-hop, route
     through intermediate JOINs and SELECT only the two final columns. Apply
     DISTINCT.
   - subject_iri / object_iri are IRI strings of the form 'bdc:<Class>_' ||
     <key column> (for example, 'bdc:WorkCenter_' || wc.WorkCenterInternalID)

⚠️ Do NOT touch master_data / structural_data / transaction_data / partition /
   datatype_properties. They were decided in earlier steps or are scheduled
   for the next step. Organize the relationships section only.

⚠️ After modifying the YAML, always confirm yaml.safe_load() parses
   successfully, and if it breaks, briefly explain what went wrong, fix it,
   and verify again.

Finally, show the result in a table:
| free-form candidate (before) | formal relationship (after) | view_name | sql_file | notes |

The deliverables of this step come in pairs. In the YAML, relationships[*].source points to the view that realizes each relationship and to the .sql file that contains the view body. The actual SQL files are stored under ingestion/kgr_views/, one file per view. In the next post, Part 3, the KGR view creation script reads these YAML paths and loads each SQL body into HANA as a CREATE VIEW statement.

Vibe Coding: organizing `datatype_properties` in the YAML

With the classes ready, the next task is to persist which columns will become attributes (owl:DatatypeProperty) on each class. The "what to persist" decision goes into the YAML; the actual Turtle definitions are produced by the LLM in Section 6 from the YAML.

📥Input
ingestion/dp_mapping.yaml: the six DPs in master_data (with relationships now populated)
docs/dp_specs/CSN_SUMMARY.md: column list + business meaning per DP
HANA PUBLIC.VIRTUAL_COLUMNS: DATA_TYPE_NAME per column (for XSD type mapping)
📤Output
ingestion/dp_mapping.yaml update: master_data[*].datatype_properties populated for each DP (column / property / range)
Report of omitted / excluded columns (with reasons)

Populate datatype_properties for each DP under master_data in
ingestion/dp_mapping.yaml.

[Input materials]
- ingestion/dp_mapping.template.yaml : the datatype_properties form + XSD
  mapping rules are documented as comments. Follow that form exactly.
- ingestion/dp_mapping.yaml : kg_class and partition for each DP under
  master_data are now decided
- docs/dp_specs/CSN_SUMMARY.md : column list + business meaning per DP
- Direct query of HANA PUBLIC.VIRTUAL_COLUMNS : XSD type mapping based on
  DATA_TYPE_NAME of rows whose SCHEMA_NAME is each DP's virtual_table_schema

[XSD type mapping rules]
- NVARCHAR / VARCHAR / STRING            → xsd:string
- INTEGER / BIGINT / SMALLINT / TINYINT  → xsd:integer
- DECIMAL / DOUBLE / REAL / FLOAT        → xsd:decimal
- DATE                                    → xsd:date
- TIMESTAMP / SECONDDATE                  → xsd:dateTime
- BOOLEAN                                 → xsd:boolean

[Column selection rules]
Include:
- Name / Description (label · comment candidates)
- business codes (ProductType, MaterialGroup, and so on)
- amount / quantity / count
- business dates (ValidFrom / ValidTo / DocumentDate, and so on)

Exclude:
- GUID / UUID (for example, ProductUUID, *_GUID)
- audit metadata (CreatedAt / CreatedBy / LastChangedAt / LastChangedBy)
- ETag / Version (for example, SAP_EntityChangeDate, SAP_ETag)
- soft-delete flags (IsDeleted / IsArchived / DeletionIndicator)
- FK columns (already persisted as ObjectProperties in relationships)

[Form]
Add a datatype_properties list to each DP under master_data:
  datatype_properties:
    - column: "<source column name, e.g., WorkCenterName>"
      property: "<bdc:camelCase, e.g., bdc:workCenterName>"
      range: "<XSD type, e.g., xsd:string>"

⚠️ Do NOT touch master_data / structural_data / transaction_data / partition /
   relationships. Add only master_data[*].datatype_properties.

⚠️ For DPs with a partition (for example, Product), persist
   datatype_properties at the parent class level (bdc:Product). Do not
   persist them separately per subclass (FinishedGood / SemiFinished /
   RawMaterial).

[Self-verification]
After modifying the YAML, confirm yaml.safe_load() parses. If it breaks,
fix it and verify again.

Finally, report:
- How many columns were added per DP
- The list of excluded columns + reason (GUID / audit / etc.)

A person scans the reported exclusion list and confirms only whether "this column is actually domain-important and was dropped" by mistake. In most cases, the rules apply cleanly.

The next Section 6 covers how this ontology structure is delegated to the LLM to produce the draft Turtle, and how labels and comments are written.

Section 5 deliverables:

Step	Deliverable	Role
Final ontology structure confirmed	Ontology diagram (6 MasterData + 1 StructuralNode + 6 relationships)	Blueprint for Section 6 Turtle authoring
relationships organized	`dp_mapping.yaml`'s `relationships` section replaced from Section 2 / Section 4 free-form candidates with the formal form (name / domain / range / source)	Direct input for Section 6 Turtle authoring
KGR view SQL bodies authored	`ingestion/kgr_views/<view_name>.sql` files (one file per view, the SELECT body)	The Part 3 KGR view creation script reads them and loads them into HANA as CREATE VIEW
datatype_properties organized	`dp_mapping.yaml`'s `master_data[*].datatype_properties` populated (column / property / range)	Direct input for Section 6 Turtle authoring

6. Drafting the Ontology Turtle with AI, and Writing Labels

Working through Sections 2–5 accumulated every ontology decision in dp_mapping.yaml: category classification, VT / synonym mapping, kg_class, partition, and relationships. In this step, that YAML is converted to W3C standard Turtle format, while semantic vocabulary such as rdfs:label, rdfs:comment, and skos:altLabel is added in parallel.

The key point is that a person does not maintain the entity list in their head. The YAML is the SSoT of decisions, so a single LLM prompt, "convert this YAML to Turtle", produces the draft.

📥Input (entire Section 6)
ingestion/dp_mapping.yaml: the SSoT accumulated across Sections 2–5 (category, kg_class, synonym, partition, relationships)
docs/dp_specs/CSN_SUMMARY.md: columns, amounts, and quantities per DP — reference for the domain vocabulary in DatatypeProperty and label / comment
(Optional) 02_verify_joins.py verification report: evidence that relationships are alive. Reference for memos such as row counts in comments
📤Output (entire Section 6)
ingestion/04_generate_ontology.py: a Python script that persists the TTL text as a multi-line string and writes it to ingestion/ontology/bdc_dp_ontology.ttl (using only pathlib, no external libraries such as rdflib)
ingestion/ontology/bdc_dp_ontology.ttl: the script output — classes + ObjectProperty + DatatypeProperty + multilingual labels and comments + skos:altLabel synonyms
Used in: Part 3 Section 5 TTL generation (loaded into HANA KGE)

Vibe Coding: YAML → ontology.ttl generation

Write a Python script ingestion/04_generate_ontology.py that takes
ingestion/dp_mapping.yaml as input and generates a W3C Turtle ontology.

[Output form]
- Persist the entire TTL inside the Python script as a multi-line string
  (ONTOLOGY = \"\"\"...\"\"\") and write it to
  ingestion/ontology/bdc_dp_ontology.ttl.
- Use only pathlib, no external libraries. Do NOT use rdflib for builder
  code. Author the TTL text yourself and persist it as a string.

[Input materials]
- ingestion/dp_mapping.yaml : the SSoT of every ontology decision
  - master_data[*].kg_class : class name
  - master_data[*].partition : Class Partition (generate subclasses if present)
  - master_data[*].datatype_properties : DatatypeProperty definitions (column,
    property, range)
  - structural_data[*].kg_class : StructuralNode hierarchy
  - relationships[*] : ObjectProperty definitions (name, domain, range,
    description)
- docs/dp_specs/CSN_SUMMARY.md : reference for label / comment domain
  vocabulary
  (the names and types of datatype_properties items in the YAML are already
   decided; only the label / comment phrasing in business vocabulary comes
   from here)

Authoring rules:
1. Prefix declarations (bdc:, rdfs:, rdf:, owl:, skos:, xsd:)
2. Class hierarchy:
   - kg_class values in master_data are rdfs:subClassOf bdc:MasterData
   - kg_class values in structural_data are subclasses of bdc:StructuralNode
   - DPs with a partition have the subclasses under partition.parent_class as
     rdfs:subClassOf; if partition.disjoint=true, also owl:disjointWith
3. Add rdfs:label and rdfs:comment to every class (multilingual: @en, @ko)
4. Define each item in relationships as owl:ObjectProperty
   (domain / range / label / comment)
5. Define each item in master_data[*].datatype_properties as
   owl:DatatypeProperty:
   - bdc:<property> a owl:DatatypeProperty ;
       rdfs:domain bdc:<kg_class> ; rdfs:range <range> ;
       rdfs:label ... ; rdfs:comment ... .
   - Take label / comment from the column descriptions in CSN_SUMMARY
     (multilingual @en/@ko).

⚠️ Do NOT add skos:altLabel (synonyms) in this step. Handled separately.
⚠️ Follow the YAML exactly. Do not add relationships or classes freely.
⚠️ Do NOT persist implementation metadata (view_name / sql_file) from
   relationships[*].source into the Turtle. The ontology contains semantics
   only (domain / range / label / comment). Implementation assets (views,
   SQL) are managed in separate .sql files.

[Self-verification — not inside the script, but as your own self-check]
Run the script once and parse the generated TTL with rdflib.Graph().parse()
to confirm it parses. If it breaks, briefly explain what went wrong, fix it,
and verify again. Hand over the final version in a parsing-passed state.

Roles:

LLM: authoring Turtle from the YAML, maintaining label · comment · domain · range consistency, multilingual expression
Domain expert: skims the class hierarchy and relationship direction in a visualization tool to confirm they match the YAML decisions, and reviews the business tone and multilingual phrasing of labels and comments

Reviewing the ontology with visualization / modeling tools

A person reviews the tone and multilingual phrasing of labels and comments. The class hierarchy, ObjectProperty definitions, and domain / range constraints were decided in the YAML, so the LLM's output can be trusted as-is.

Before loading the draft from the LLM, a visual review is a safety net. Confirm graphically that the class hierarchy, ObjectProperty direction, and domain / range constraints came out as intended. A few options:

Protégé: open-source ontology editor developed at Stanford. Opens a TTL file and shows the class hierarchy and ObjectProperty as a tree. Useful for a light review.
SAP HANA Cloud Knowledge Graph Engine: query the loaded KG directly with SPARQL for verification. Because ontology and instances live on a single platform, post-load verification is fast.
Metaphactory: an Enterprise KG platform officially integrated with SAP HANA Cloud KGE. Supports ontology editing, visual modeling, data entry, and SPARQL queries in a single interface. Suited for operating an ontology in a collaborative environment.

In a production project, ontology design and long-term maintenance should be done with modeling and governance tools such as Protégé or Metaphactory. The AI-based workflow in this post is not intended to replace those tools. Its value is that it creates a strong first draft quickly, especially when you are exploring a new domain or learning how SAP BDC metadata maps into KG classes and relationships. For scenario-based projects, this first draft is often sufficient to validate the core classes, relationships, and Competency Questions before formalizing the ontology in dedicated modeling tools. Once you gain experience with this workflow, you will be better prepared to review, refine, and operate the ontology in those tools. This is also aligned with where the tooling market is moving: modeling environments increasingly use AI to assist semantic modeling, vocabulary creation, and relationship discovery.

In our project, we reviewed with Protégé, then generated the final TTL with 04_generate_ontology.py (covered in detail in the next post, Part 3).

Synonyms: applying skos:altLabel in practice

Part 2-1 Section 1 covered the standards basis of the skos:altLabel pattern. Here we examine how it is applied in practice.

Situations where synonyms are needed:

When the Agent must link diverse expressions in user questions — "공급사," "벤더," "Vendor," "Supplier" — to the same class
When context_loader.py injects ontology metadata into the LLM, so that the LLM generates the correct SPARQL regardless of the user's vocabulary

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

bdc:Supplier a owl:Class ;
    rdfs:label    "Supplier"@en ,
                  "공급사"@ko ;
    skos:altLabel "공급업체"@ko ,
                  "벤더"@ko ,
                  "Vendor"@en ;
    rdfs:comment  "A counterparty that supplies materials or services."@en .

This is the step deliberately omitted from the first Vibe Coding. Synonyms depend on industry, domain, and in-house vocabulary, so handing them off in a separate pass after the ontology draft is in place produces better quality.

🎯 Vibe Coding: bulk addition of skos:altLabel synonyms
Purpose: add user vocabulary variants (synonyms) to the ontology draft from the first Vibe Coding as skos:altLabel
Input:
ingestion/04_generate_ontology.py (the first Vibe Coding deliverable — the TTL string is persisted as a multi-line string)
Domain context (SAP industry vocabulary / in-house jargon / English vs Korean phrasing differences)
Deliverable: updated 04_generate_ontology.py — skos:altLabel triples added to the TTL string and @prefix skos: added to the top prefix block. Re-running updates bdc_dp_ontology.ttl.

Edit the TTL string (ONTOLOGY = \"\"\"...\"\"\") inside
ingestion/04_generate_ontology.py directly to add skos:altLabel synonyms to
each class. The targets are every class in master_data and structural_data
plus the subclasses of every Class Partition.

Rules:
1. Add @prefix skos: <http://www.w3.org/2004/02/skos/core#> . to the top prefix
   block
2. Leave rdfs:label as the "official name"; add only the other expressions
   users actually use as skos:altLabel
3. If both Korean and English variants are possible, add both (keep @ko / @en
   language tags)
4. SAP industry vocabulary (for example, Supplier → Vendor/벤더/거래처, Plant →
   공장/사업장, BillOfMaterial → BOM/명세서)
5. If you are uncertain for a given class, skip it and report which classes
   were skipped at the end
6. Do NOT introduce external libraries such as rdflib. Edit the existing
   multi-line string directly.

[Self-verification]
After re-running the script, parse the generated TTL once with
rdflib.Graph().parse() to confirm. If it breaks, fix and verify again. Hand
over the final version.

A person reviews only whether industry-specific terms or in-house jargon were omitted. If the LLM reports any "skipped classes," fill in the in-house vocabulary directly and run one more pass.

Synonyms are possible without SKOS. A custom property, or packing every variant into rdfs:label, also makes search work. The reason to use skos:altLabel is not to enable search; it is two-fold: the preferred / alternative role distinction is standardized and built in, and when later extending into cross-system mapping (skos:exactMatch and similar), the same vocabulary family is reused. For the detailed trade-off, consult Part 2-1 Section 1, "Can synonyms work without SKOS?"

Why this work is done at the ontology stage: it is reused in the Agent

Labels and comments are not just readability aids. They are the input that is injected as domain vocabulary into the LLM in the Part 4 Agent:

Ontology metadata loaded at Agent startup: class labels and comments are persisted in the system prompt so the LLM learns "bdc:WorkCenter is a work center located in a Plant, producing Finished Goods" → smarter SPARQL authoring
SPARQL result interpretation: with only URIs (bdc:WorkCenter_Z_ASM3), the LLM cannot read; with a label "Z_ASM3", it generates an answer using the business name directly
Multilingual answers: a Korean question prompts the Agent to retrieve the @KO label / comment first and answer in Korean, and English for English speakers. Multilingual support is delivered through the ontology alone, without backend code changes.

→ The quality of labels and comments at this stage is the quality of the Agent's answers. "Polish them later" is not the right approach; persist them alongside the ontology load. That is the standard.

Section 6 deliverables:

Step	Deliverable	Role
Ontology draft	`ingestion/ontology/bdc_dp_ontology.ttl` (draft)	Classes + ObjectProperty + DatatypeProperty definitions
Multilingual label · comment authoring	`bdc_dp_ontology.ttl` (final)	`@en` / `@ko` multilingual labels and comments + `skos:altLabel` synonyms

→ In the next post (Part 3), this bdc_dp_ontology.ttl is loaded into SAP HANA Cloud KGE.

Summary

This post covered:

KG vs SQL classification: structural relationship traversal → KG, numeric aggregation → SQL. Entities with no outgoing relationships (Customer) become SQL lookups
Class Partition: separating different kinds of entities within a single table (Product by MaterialType) into distinct classes. Relationship directionality + LLM reasoning
Final ontology: two branches (MasterData / StructuralNode), six master classes + one bridge (PSL)
Drafting with AI: SAP ODM vocabulary lets the LLM produce a strong draft
rdfs:label authoring rules: applied to every instance, class, and property. The minimum requirement that makes the KG readable by the LLM

The deliverable of this post is a single file, bdc_dp_ontology.ttl , the blueprint of the KG. The next post covers the pipeline that fills that blueprint with actual data.

What's Next

The blueprint is complete. What remains is reading actual data from SAP BDC Data Products, transforming it into the KG, and loading it into SAP HANA Cloud KGE.

Part 3 – Data Pipeline from BDC to Triple Store starts with metadata exploration using PUBLIC.VIRTUAL_COLUMNS, covers the relationship SQL View pattern that compresses multi-hop relationships into 1-hop, the TTL generation pipeline, and the Triple Store inside SAP HANA Cloud KGE.

Stack: SAP BDC Data Products · HANA Cloud KGE · FastAPI · React · Claude (Anthropic / AI Core) Code: github.com/claudiopark86/sap-bdc-kge-agent-workshop

References

Ontology Development 101: A Guide to Creating Your First Ontology — Noy & McGuinness, Stanford 2001. https://protege.stanford.edu/publications/ontology_development/ontology101.pdf
A Direct Mapping of Relational Data to RDF — W3C Recommendation, 2012-09-27. https://www.w3.org/TR/rdb-direct-mapping/
R2RML: RDB to RDF Mapping Language — W3C Recommendation, 2012-09-27. https://www.w3.org/TR/r2rml/
OWL 2 Quick Reference Guide — W3C Recommendation, 2012-12-11. (§2.7 Annotations lists rdfs:label and rdfs:comment as built-in annotation properties.) https://www.w3.org/TR/owl2-quick-reference/
SAP HANA Cloud Integration with Metaphactory for Knowledge Graph Modelling — SAP Community Blog. https://community.sap.com/t5/technology-blog-posts-by-sap/sap-hana-cloud-integration-with-metaphactory-for-knowledge-graph-modelling/ba-p/14390776
HANA Cloud Data Products Consumption — SAP Tutorial. https://developers.sap.com/tutorials/hana-cloud-data-products-consumption.html
Data Product Support in SAP HANA Cloud — SAP Help Portal. https://help.sap.com/docs/hana-cloud/sap-hana-cloud-administration-guide/data-product-support-in-sap-hana-cloud-internal?locale=en-US

Code Connect 2026: Final Info Before We Kick Off!

2026-07-06T11:02:20.615000+02:00

Code Connect 2026 is just around the corner! From July 13–16, 2026, the SAP developer community will gather in St. Leon-Rot, Germany – onsite and online.

Here’s everything you need to know before we get started.

We Are Fully Booked!

All onsite tickets are fully booked - thank you for the amazing interest!

If you couldn’t secure a ticket:

Join the waiting lists on Code Connect 2026 in case seats become available.
Follow selected sessions via live stream or Microsoft Teams link.

Even if you're not onsite, you can still be part of Code Connect. Selected sessions will be streamed live, and recordings of some sessions will be available afterwards. Check back soon for details.

UI5con (July 14)

Main stage sessions will be live streamed on YouTube.
Check the agenda to see which sessions are streamed.

re>≡CAP (July 15)

Main stage sessions will be broadcasted.
Some sidetracks (W1/W2) can be attended via Microsoft Teams link.
Check the agenda to see which sessions are broadcasted or available via Microsoft Teams link.

HANA Tech Con (July 16)

The links will be announced on the event day.

The Agendas Are Live

The full program is already available - time to plan your schedule!

Check-In opens at 8.00 AM every day. Please bring the QR code with you that you can find in your ticket.

July 13 – Code Jams & Community Meetup

Hands-on Code Jams:

OpenUI5
CAP
AI Agents

Informal pre-event meetup (no registration needed):
Ihle Besen, Höfe am Sträßel 3, 69231 Rauenberg
5:00 PM CEST

July 14–16 – Main Conference Days

Explore all agendas:

July 14: UI5con
July 15: re>≡CAP
July 16: HANA Tech Con

On July 14 also the HANA AI CodeJam takes place.

Location

Code Connect takes place at:

SAP-Allee 27
68789 St. Leon-Rot, Germany

Find detailed information on directions, parking, and public transport here.

Final Tips

Bookmark your favorite sessions in advance
Arrive early for popular sessions (rooms fill quickly!)
Bring your laptop for Code Jams and hands-on sessions/ workshops
Don’t miss the networking moments - some of the best conversations happen in between sessions
Follow the agendas closely for last-minute updates

See You Soon!

We’re looking forward to an inspiring week of learning, sharing, and connecting.

See you at Code Connect 2026!

Building Vector Search Applications with SAP HANA Cloud and LangChain.js

2026-07-07T11:27:33.345000+02:00

Imagine your customer types “something comfortable for working from home” into your shop’s search bar. There’s no “comfortable” column in your product table. No “work from home” tag either. And yet your store somehow needs to surface the ergonomic chair, the noise-cancelling headphones, and the standing desk.

That gap between what people say and what your database stores is exactly where vector search lives. With @SAP/hana-langchain, your SAP HANA Cloud database doesn’t just store your data. It understands it.

The full walkthrough, with every line of code, every output, and every config option, lives on GitHub: blogs/blog-post.md. The sections below focus on the ideas worth remembering, paired with the bits of code and output that bring them to life.

What it is

@SAP/hana-langchain is the official open-source bridge between SAP HANA Cloud’s Vector Engine and LangChain.js. It turns your enterprise database into a first-class AI retrieval layer for RAG, semantic search, recommendations, and intelligent Q&A, all running where your data already lives.

Two lines and you have a vector store:

npm install @langchain/core @langchain/classic langchain
npm install @sap/hana-langchain

Searching by intent, not by keywords

Let’s walk through the real story. A customer is setting up their home office. They open your store and search:

“comfortable work from home setup”

Your catalogue has hundreds of products. Keyword search? Zero relevant hits. With HanaDB? Watch what happens.

import { HanaDB, HanaInternalEmbeddings } from "@sap/hana-langchain";

// Embeddings happen INSIDE HANA. No external API. No data leaving your DB.
const embeddings = new HanaInternalEmbeddings({
  internalEmbeddingModelId: "SAP_NEB.20240715",
});

const store = new HanaDB(embeddings, {
  connection: client,
  tableName: "PRODUCT_CATALOG",
});
await store.initialize();

const results = await store.similaritySearch(
  "comfortable work from home setup",
  2,
);

The output:

[
  Document {
    pageContent: 'Ergonomic office chair with lumbar support and adjustable armrests',
    metadata: { category: 'furniture', price: 449, in_stock: true }
  },
  Document {
    pageContent: 'Professional espresso machine with built-in grinder',
    metadata: { category: 'appliances', price: 899.99, in_stock: false }
  }
]

The chair makes obvious sense. The espresso machine? Also surprisingly on-brand for “working from home.” The model picked up on intent that no SQL LIKE ever could.

Cosine vs. Euclidean: pick your distance

So how does similaritySearch actually decide which products are “closest” to the query? Each document and the query are turned into vectors, and then HanaDB applies a distance metric to measure how far apart they are. The library supports two: cosine (the default) and Euclidean. You pick which one you want with a single config option when you create the store.

The choice matters because the two metrics score the same set of candidates differently. Take the query “high quality audio headphones” and run it under both strategies. Same data, same embedding model, different scoring philosophy:

COSINE Similarity Results (higher = more similar)
[0.7219] Wireless noise-canceling headphones with premium sound quality
[0.5506] Professional studio microphone for podcasting and streaming
[0.5206] Bluetooth speaker with deep bass and 20-hour battery

EUCLIDEAN Distance Results (lower = more similar)
[0.7086] Wireless noise-canceling headphones with premium sound quality
[0.9048] Professional studio microphone for podcasting and streaming
[0.9251] Bluetooth speaker with deep bass and 20-hour battery

Both metrics pick the same winner here, but notice the gap between first and second place: cosine spreads the candidates by relative similarity, Euclidean by raw distance in vector space. As a rule of thumb, cosine is the right default for text, because it only cares about the direction the vectors point in, not how long they are. Euclidean is a better fit when the actual position of the vectors carries meaning, for example when your embeddings come from numerical features rather than text. If you’re not sure which to pick, leave it on cosine.

Adding diversity when you need it: MMR

Sometimes “most similar” is exactly what the user wants. A shopper who searches for “wireless headphones” expects a list of wireless headphones, and similarity search delivers that perfectly well.

But there are spots in the same product journey where pure similarity hurts the experience. The classic case is the “customers also viewed” strip on a product detail page. A shopper looking at a premium open-back studio headphone doesn’t need to see four more premium over-ear headphones below it. They’d be much better served by a strip that also shows them a different form factor, a different price tier, or a noise-cancelling alternative.

That’s the job of Maximal Marginal Relevance (MMR). Instead of returning the top-k most similar documents, MMR picks results that are both relevant and different from each other. You retrieve a larger candidate pool; MMR walks it, picking the next item that maximises relevance while penalising redundancy with what’s already been chosen. One lambda knob tunes the balance between relevance and diversity.

Same vector store, same query, two different methods. First, plain similarity search:

// Plain similarity search: top-4 candidates ordered by closeness alone
const similar = await vectorStore.similaritySearch(
  "premium wireless over-ear headphones",
  4,
);

similaritySearch top 4:
  1. AudioMax Pro 5     (over-ear-wireless, $349.99)
  2. AuroraSound Pro    (over-ear-wireless, $379.99)
  3. AudioMax Buds 5    (true-wireless,     $299.99)
  4. QuietShield Ultra  (over-ear-wireless, $429.99)

Three of the four results are premium over-ear wireless headphones, almost interchangeable for the shopper. Not a useful “customers also viewed” strip.

Now the same query, through MMR:

// MMR: pick 4 from a wider candidate pool while penalising redundancy.
// lambda = 0.5 balances relevance and diversity evenly.
const recommendations = await vectorStore.maxMarginalRelevanceSearch(
  "premium wireless over-ear headphones",
  { k: 4, fetchK: 12, lambda: 0.5 },
);

maxMarginalRelevanceSearch top 4:
  1. AudioMax Pro 5     (over-ear-wireless, $349.99)
  2. FlexFit Sport      (neckband,           $89.99)
  3. AuroraSound Pro    (over-ear-wireless, $379.99)
  4. TuneCore 510       (on-ear-wireless,    $49.99)

The top match is still the most relevant premium over-ear pair, but the next three deliberately span different form factors and price tiers. The shopper now sees an actual mix to compare, all from one method swap on the same vector store and the same product catalogue.

Use similaritySearch when the goal is the closest match. Reach for maxMarginalRelevanceSearch when the goal is coverage: recommendation strips, RAG context that spans multiple sub-topics, related-articles modules, or anywhere a single dominant theme would crowd out everything else.

Filtering that speaks JavaScript

Semantic search is great. Semantic search plus structured filters is unbeatable. HanaDB’s filter syntax will feel instantly familiar to anyone who’s ever written a MongoDB query:

// In-stock electronics under $500
const filter = {
  $and: [
    { in_stock: true },
    { category: "electronics" },
    { price: { $lt: 500 } },
  ],
};

const results = await store.similaritySearch("best audio quality", 10, filter);

And the result is exactly what the filter promised: only in-stock electronics, all under $500, ranked by audio quality:

[
  { pageContent: 'Premium wireless headphones with spatial audio...',  price: 349.99, in_stock: true },
  { pageContent: 'Budget wireless earbuds with decent sound...',       price:  49.99, in_stock: true },
  { pageContent: 'Bluetooth over-ear headphones with active noise...', price: 249.99, in_stock: true },
  { pageContent: 'Wireless noise-canceling headphones with 30-hour...',price: 299.99, in_stock: true }
]

You get the full operator suite ($lt, $lte, $gte, $between, $in, $nin, $like, $contains, $and, $or) all compiled down to native HANA SQL. No JavaScript-side filtering. No surprises at scale.

Letting the LLM write its own filters

Here’s where it gets fun. What if a user types “Show me AudioMax electronics under $400 with good ratings”? You could build a custom intent parser. Or you could let the LLM do it for free, with the HanaTranslator:

const retriever = SelfQueryRetriever.fromLLM({
  llm,
  vectorStore: store,
  documentContents: "Product description for an e-commerce catalog",
  attributeInfo,                              // describe your metadata
  structuredQueryTranslator: new HanaTranslator(),
});

await retriever.invoke("Show me AudioMax electronics under $400 with good ratings");

Behind the scenes, the LLM emits:

{
  $and: [
    { brand: "AudioMax" },
    { category: "electronics" },
    { price:  { $lt:  400 } },
    { rating: { $gte: 4 } }
  ]
}

Natural language in. Structured filter out. Vector search on top. Zero glue code.

There’s more in the box

What you’ve seen so far is the foundation. The library ships with three more capabilities, each big enough to deserve its own deep-dive:

Cross-encoding reranking with HanaReranker. Re-score your top candidates for surgical-precision results, the secret sauce behind great RAG and customer-facing search.
Knowledge graphs & SPARQL with HanaRdfGraph. Query RDF data, build natural-language Q&A over relationships, and combine graph reasoning with vector search.
Performance at scale with Map Merge, HNSW indexes, and specific metadata columns. Roughly 9× faster bulk inserts, sub-second search at million-document scale, and faster filtered queries.

Stay tuned for more updates and deep dives into each of these capabilities!

Get the code: SAP/langchainjs-integration-for-sap-hana-cloud | Read the full guide: blog-post.md

Calculation View Features of 2026 QRC2

2026-07-08T14:50:53.797000+02:00

Within the time frame of 2026 Q2, several new calculation view features have been released in SAP Business Application Studio when connected to SAP HANA Cloud database QRC2. Some of these features are highlighted below. You can find examples that illustrate the individual features here. An overview of features of other releases can be found here.

Optimized Redeployment

When a calculation view is redeployed in a stacked scenario, all dependent objects in the same HDI container are normally dropped and sequentially recreated. This default behavior avoids cascading revalidations but comes with a cost: privileges on dependent objects are temporarily, or in cross-container scenarios potentially permanently, revoked, and the full recreate cycle adds significant deployment time.

Optimized redeployment addresses this. Instead of dropping all dependents upfront, a consistency check determines which dependent views are still valid after the change. Views unaffected by the redeployed calculation view are kept as-is and skipped entirely. This reduces both the time spent recreating unaffected views and the privilege reassignment overhead.

To enable optimized redeployment for calculation views, add the following parameter to the hdi-deploy invocation in package.json:

"start": "node node_modules/@sap/hdi-deploy/deploy.js --parameter com.sap.hana.di.calculationview/optimized_redeploy=true"

A global parameter (optimized_redeploy=true) is also available and activates the behavior for all HDI object types that support it.

Replace Instead of Drop and Recreate During Redeployment

By default, calculation views are dropped and recreated during redeployment. Dropping a view revokes all privileges associated with it. Privileges defined in HDI roles of the same container are automatically regranted at the end of deployment, but direct privileges held by roles outside the current HDI container are permanently lost.

The new replace option substitutes the drop-and-recreate cycle with an in-place replacement. Because the object is never dropped, existing privileges are preserved throughout deployment. The benefit is most significant when combined with optimized redeployment: without it, dependent views are dropped before the root view is replaced, so they never benefit from the replace logic. With both options active, the replace strategy also applies to dependent views.

To enable the replace behavior, pass the following parameter:

"start": "node node_modules/@sap/hdi-deploy/deploy.js --parameter optimized_replace=true"

Combining optimized_replace=true with optimized_redeploy=true gives the strongest deployment time and privilege preservation benefit.

Active/Active Read-Enabled Hints

In an Active/Active (Read-Enabled) setup, query routing hints can now be configured at the individual calculation view level. This gives fine-grained control over whether a query is directed to the primary system or the read replica, allowing workload to be distributed and overall throughput to be increased.

Hints are evaluated only on calculation views that are directly referenced in the query.

Switching from a Join Node to a Non-Equi Join Node

A Join node can now be converted directly to a Non-Equi Join node via the node's context menu, without needing to manually rebuild the join logic.

During conversion you can choose how the resulting join condition is expressed: either graphically, based on the column display,

or as an explicit join expression.

This simplifies the refactoring of join logic and reduces manual rework. Note that features not supported by Non-Equi Join nodes, such as dynamic joins, text joins, and filter expressions, are removed automatically during the conversion.

Calculation View Status Dialog

When opening a calculation view with certain properties, a status dialog now appears and reports details about the current view state. Where applicable, the dialog also offers direct actions to resolve issues, for example, prompting you to log in to Cloud Foundry when no active database connection is found.

The dialog covers four categories:

Read-only mode: reasons why the calculation view was opened in read-only mode
Database connection: current connection status to the database
Data classification inconsistencies: detected mismatches in the data classification setting
BDC integration: whether the calculation view is used with BDC integration mode

Calculated Measures in MDS Cubes

Calculated measures can now be added to MDS Cubes and are evaluated at query runtime. This makes it possible to execute calculations at query runtime.

If a calculated measure cannot be translated into a valid MDS formula, deployment fails with a corresponding error message.

Media Handling in SAP CAP: Mixing Static and Uploaded Images in Fiori Elements V4

2026-07-09T20:15:58.012000+02:00

Hi everyone,

Introduction

When building applications with the SAP Cloud Application Programming (CAP) model and SAP Fiori Elements V4, handling media files is a common requirement. Usually, it is straightforward: first define a LargeBinary field, and the framework generates an upload control.

However, things get complicated when we need a single table column to dynamically display images from two different sources:

Static default images (loaded via CSV during deployment).
Custom images uploaded by users via the UI.

This guide covers the complete end-to-end setup to achieve this:

Data Modeling — Defining the schema with a "Traffic Cop" virtual field.
UI Annotations — Exposing the right fields to the List Report and Object Page.
Backend Logic — Intercepting OData V4 requests in Node.js to bypass UI optimizations.
HANA Deployment — Resolving common driver version conflicts during deployment.

Why I Wrote This

Recently, I was developing an application on the SAP Business Technology Platform where users needed to browse a catalog of items. Some items had static placeholder images mapped to local CSV paths, while others had high-res photos explicitly uploaded by users.

When I attempted to route these dynamically using a virtual field, my Fiori V4 List Report stubbornly displayed blank "No Image" placeholders. After hours of debugging the OData V4 network payload, I realized Fiori was optimizing my request by stripping out the hidden columns my backend logic relied on. I couldn't find a definitive guide covering this specific Fiori V4 optimization trap, so I'm sharing the bulletproof workaround I built.

First, Let's Understand the Fiori V4 Optimization Trap

Before looking at the code, it helps to understand why the standard approach fails in Fiori Elements V4.

Fiori V4 is aggressively optimized for bandwidth. When it loads a List Report, the OData $select query only asks for the columns explicitly visible on the screen. If the backend relies on a virtual field (e.g., displayImageUrl) that calculates its value based on hidden fields (like mediaType or ImageUrl), those hidden fields arrive at the backend handler as undefined. We cannot calculate a dynamic URL if the framework refuses to fetch the underlying data.

To fix this, we don't fight the UI. Instead, we let Fiori request whatever it wants, and we use a custom CAP backend hook to silently query the database for the missing fields before delivering the final payload to the browser.

Architecture Overview

This solution relies on a clean separation between the database schema, the UI annotations, and the backend Node.js service.

project-root/
│
├── db/
│   ├── data/
│   │   └── mediahandling.db-Image.csv  ← Initial data linking to static image paths
│   └── schema.cds                      ← Defines the binary, static, and virtual fields
│
├── app/
│   ├── mediahandling/                  ← Your Fiori Elements application
│   │   └── webapp/
│   │       └── images/                 
│   │           ├── image1.jpg          ← The actual static placeholder files
│   │           └── image2.jpg
│   └── annotations.cds                 ← Maps the UI controls for Fiori Elements
│
└── srv/
    ├── catalogService.cds              ← Exposes the OData service
    └── catalogService.js               ← Contains the custom 'READ' interceptor logic

Step 1: The Data Model (schema.cds)

We need an entity that stores both the binary file and the static URL, alongside a virtual field to decide which one to render.

Critical Detail: Ensure the @ui.IsImageURL: true annotation is applied directly to the virtual field here in the schema. This instructs Fiori V4 to natively allocate an avatar control in the List Report.

namespace mediahandling.db;
using { cuid, managed } from '@sap/cds/common';

entity Image: cuid, managed {
    Name        : String(100);
    Description : String(255);
    
    // Holds the static CSV path (e.g., 'images/default.jpg')
    ImageUrl    : String; 

    // The actual uploaded file data
    @Core.MediaType  : mediaType
    image       : LargeBinary;

    // The file extension/type (e.g., 'image/jpeg')
    @Core.IsMediaType: true
    mediaType   : String;

    // The "Traffic Cop" virtual field for Fiori UI display
    @ui.IsImageURL: true
    virtual displayImageUrl : String;
}

Step 2: Initializing the Mock Data (CSV)

To test this, we need to load initial records into the database. Create a file named mediahandling.db-Image.csv inside the db/data/ folder.

ID;Name;Description;ImageUrl
22222222-2222-2222-2222-222222222201;Sunset Boulevard;A beautiful vibrant sunset over the city boulevard.;images/image1.jpg
22222222-2222-2222-2222-222222222202;Mountain Peak;The highest snow-capped peak in the northern mountain range.;images/image2.jpg

Step 3: UI Annotations (annotations.cds)

In the UI annotations, we expose the virtual displayImageUrl field in the UI.LineItem (List Report) so the dynamic image renders in the table. We expose the actual image (LargeBinary) field inside the UI.FieldGroup (Object Page) so the user gets a file upload prompt when creating or editing a record.

using MyService as service from '../../srv/catalogService';

annotate service.Image with @(
    UI.FieldGroup #GeneratedGroup : {
        $Type : 'UI.FieldGroupType',
        Data : [
            { $Type : 'UI.DataField', Label : 'Name', Value : Name },
            { $Type : 'UI.DataField', Label : 'Description', Value : Description },
            { $Type : 'UI.DataField', Label : 'Upload Image', Value : image }
        ],
    },
    UI.Facets : [
        {
            $Type : 'UI.ReferenceFacet',
            ID : 'GeneratedFacet1',
            Label : 'General Information',
            Target : '@UI.FieldGroup#GeneratedGroup',
        },
    ],
    UI.LineItem : [
        { $Type : 'UI.DataField', Label : 'Name', Value : Name },
        { $Type : 'UI.DataField', Label : 'Image', Value : displayImageUrl }, 
        { $Type : 'UI.DataField', Label : 'Description', Value : Description }
    ],
    UI.HeaderInfo:{
        $Type : 'UI.HeaderInfoType',
        TypeName : 'Image Record',
        TypeNamePlural : 'Image Records',
        Title : { $Type: 'UI.DataField', Value: ID },
        Description : { $Type: 'UI.DataField', Value: Name },
        ImageUrl : displayImageUrl 
    }
);

Step 4: The Backend Interceptor (catalogService.js)

This is where the magic happens. We intercept the after('READ') event. If we detect that Fiori stripped our necessary columns (mediaType and ImageUrl), we immediately execute a lightweight database query to fetch them for the visible rows. Finally, we route the URL accordingly.

const cds = require('@sap/cds');

module.exports = cds.service.impl(async function() {
    // Dynamically grab the actual service base path (e.g., /odata/v4/my)
    const srvPath = this.path;

    this.after('READ', 'Image', async (data, req) => {
        const images = Array.isArray(data) ? data : [data];
        if (images.length === 0) return;

        // If Fiori stripped the columns to save bandwidth, we step in.
        if (images[0].mediaType === undefined && images[0].ImageUrl === undefined) {
            
            // Grab the IDs of the rows currently visible on the screen
            const ids = images.map(img => img.ID);
            
            // Query the database directly to fetch the missing fields
            const dbData = await cds.tx(req).run(
                SELECT.from(req.target)
                      .columns('ID', 'mediaType', 'ImageUrl', 'IsActiveEntity')
                      .where({ ID: { 'in': ids } })
            );

            // Stitch the missing data back into the original payload
            images.forEach(img => {
                const match = dbData.find(d => d.ID === img.ID);
                if (match) {
                    img.mediaType = match.mediaType;
                    img.ImageUrl = match.ImageUrl;
                    img.IsActiveEntity = match.IsActiveEntity;
                }
            });
        }

        // Execute the Traffic Cop logic (guaranteed to have the data)
        images.forEach(image => {
            if (image.mediaType) {
                // Route to the OData media stream for uploaded binaries
                const isActive = image.IsActiveEntity !== false;
                image.displayImageUrl = `${srvPath}/Image(ID=${image.ID},IsActiveEntity=${isActive})/image`;
            } else if (image.ImageUrl) {
                // Route to the static CSV path
                image.displayImageUrl = image.ImageUrl;
            } else {
                // Fallback placeholder
                image.displayImageUrl = 'https://dummyimage.com/200x200/cccccc/000000.png&text=No+Image';
            }
        });
    });
});

Output:

Note: Deploying to SAP HANA Cloud

When transitioning from a local SQLite setup to SAP HANA Cloud, we may encounter an NPM dependency error when starting the hybrid profile.

If the project is running @SAP/cds version 9, but the latest @cap-js/hana driver expects version 10, the standard npm install will fail with an ERESOLVE conflict. We can safely bypass this strict peer dependency check and link the driver by running the following:

npm install @cap-js/hana --legacy-peer-deps

Once installed, cds watch --profile hybrid command will connect to the HANA instance seamlessly.

Conclusion

By shifting the data-retrieval logic into the Node.js backend rather than relying on messy UI workarounds or forced hidden columns, we maintain the strict performance benefits of Fiori Elements V4 while delivering a seamless, dynamic user experience.

SAP HANA Cloud release June 2026 Round-up

2026-07-15T16:05:19.094000+02:00

Dear SAP HANA Cloud Enthusiasts,

We are excited to share a collection of the latest videos, blog posts, and resources highlighting the SAP HANA Cloud Q2 2026 release.

	What’s New Teaser Explore the latest innovations in SAP HANA Cloud with Lead Product Manager Thomas Hammer, as he shares his top highlights from the newest release in this engaging teaser. Watch it now on YouTube.
What’s New blogpost Intrigued by the teaser? Explore our "What’s New in SAP HANA Cloud in June 2026" blogpost for an in-depth look at the innovations and find valuable links to further demos and content. Read it here!
	What's New Webinar Prefer watching over reading? Our 'What’s New' webinar is just for you! Join our Product experts for an in-depth view of the latest features. Available to watch anytime here!

Don’t miss out on all the content and remember to follow us in the SAP HANA Community.

Remember to check our content following the # whatsnewinsaphanacloud tag: here

Don’t forget to subscribe and follow SAP HANA Cloud on YouTube to always stay up-to-date regarding the most recent innovations in SAP HANA Cloud.

All the best,

Andrea on behalf of the SAP HANA Cloud team

#SAP HANA Cloud, SAP HANA database #SAP HANA Cloud

#whatsnewinsaphanacloud

From Preview to Production: Get Started with the SAP HANA Cloud's Agentic Data Exploration Tools

2026-07-15T21:25:57.846000+02:00

At SAP TechEd 2025, we shared a vision: what if exploring data felt less like archaeology and more like a conversation? We introduced two capabilities designed to make that real and the response told us we were onto something. Fast forward to today. That vision is now in production. SAP HANA Cloud's data exploration capabilities are generally available, and customers can start using them right now.

If you followed the TechEd announcement, you will remember these capabilities as the Discovery Agent and the Data Agent. As they matured from prototype to production, so did our thinking about what to call them.

They are now formally known as the Database Object Discovery Tool and the Data Retrieval Tool - together, the SAP HANA Cloud data exploration tools. The rename reflects a natural evolution: as these capabilities became production-grade, composable building blocks that any agent, application, or workflow can invoke, the "tool" framing became the more precise one. The underlying power is the same.

Note: **Upcoming Agents. Subject to change as we evolve our roadmap

Why This Matters - For Everyone

Whether you are a developer building an AI-powered application, or a business stakeholder who simply wants answers from data, these tools close a gap that has existed for a long time.

For business users and decision makers:

You no longer need to know where data lives to find it. The Database Object Discovery Tool searches across tables, views, and relationships based on what you describe, or query about.
You no longer need SQL to get results. The Data Retrieval Tool translates a plain language request into a query and returns the answer, no manual lookup, no schema expertise required.
The experience feels conversational, even though sophisticated discovery and query generation is happening beneath the surface.

For developers and architects:

Production-grade interfaces: stored-procedure-based (AI_OBJECT_DISCOVERY and AI_DATA_RETRIEVAL) that integrate cleanly into any application or agent workflow.
Composable by design: wire them into an MCP server or call them directly from your own tooling & agents.
Context inherited automatically: the Custom Database Objects Knowledge Graph continues to serve as the semantic backbone, so your applications gain that contextual understanding without you having to build it.

Getting Started

There is no additional infrastructure to provision. If you have access to SAP HANA Cloud with the Natural Language Processing & Triple Store services enabled, and an SAP AI Core subscription, you have access to these tools today.

The pattern is straightforward:

Discover - Describe what you are looking for in natural language. The Database Object Discovery Tool searches the HANA catalog's knowledge graph & RAG layer and returns the relevant tables, views, and columns.
Retrieve - Pass that context to the Data Retrieval Tool along with your question. It generates and executes the appropriate query and returns results.

Try It Yourself - Explore Data with SAP HANA Cloud Data Exploration Tools

The SAP Developer Tutorials has a step by step guide that walks you through setting up both tools and running your first natural-language query against SAP HANA Cloud. It covers the key features that make HANA Cloud well-suited for business AI, and gets you hands-on quickly.

SAP HANA Cloud Central Tooling

What's Next: Taking the Tools Further with MCP

These tools are built to be composable and one of the most powerful ways to use them is through the Model Context Protocol (MCP). In the next post in this series, we will walk through how to spin up a local MCP client that connects directly to the Database Object Discovery Tool and the Data Retrieval Tool, and what that unlocks for agentic AI workflows on top of SAP HANA Cloud.

If you have been curious about how SAP HANA Cloud fits into the broader agentic architecture picture at the protocol level that one is for you.

The Data Exploration Tools are more than a new capability, they mark SAP HANA Cloud's evolution toward an agentic database that not only manages data, but also enables users and AI agents to understand, explore, and leverage it intelligently. This is the direction SAP HANA Cloud is moving and there is more to come.

Certified as an SAP Data Architect? Join the practitioner discussion

2026-07-22T11:25:53.802000+02:00

Congratulations to everyone who has completed or is working toward the new SAP Data Architect certification. Becoming certified is an important milestone. It shows that you are building the knowledge needed to design scalable, governed, AI-ready data ecosystems and connect architecture concepts to business outcomes.

But certification is also just the beginning. Once you start applying these concepts in real projects, new questions naturally come up:

How do I translate architecture principles into implementation decisions?
How should I approach governance, metadata, ownership, and data quality?
How do I connect SAP Business Data Cloud with existing SAP and non-SAP landscapes?
How do data architecture choices change when AI, advanced analytics, or data products are involved?
What patterns are other practitioners using in the field?

That is where the Data Professionals group comes in. The Data and Analytics Learning Group is the right place to learn, prepare, and ask questions about learning content. The Data Professionals group is the next step: a practitioner community for discussing real-world architecture, governance, integration, analytics, AI, and SAP Business Data Cloud scenarios with peers, SAP experts, customers, and partners.

If you have completed the certification, are preparing for it, or are applying the learning journey in your current role, we invite you to join the practitioner discussion here. Bring your project questions, your lessons learned, your architecture challenges, and your practical experience.

Why don’t you start with one real-world data architecture question you would like to discuss with other practitioners?

reCAP 2026 – Recordings of our Annual CAP Developer Conference

2026-07-22T12:07:54.874000+02:00

On 15 July 2026, the CAP community came together for reCAP 2026 in St. Leon-Rot. Again, tickets were sold out within just a few minutes. We had more than 400 participants onsite and many more joining online.

For everyone who couldn’t attend live, most sessions were recorded. Below is a summary of the recorded sessions, along with links to the recordings. You can find all recordings on YouTube.

Opening & Keynote

Intro by Ole Lilienthal
Setting the stage, Ole gave an overview of the Autonomous Enterprise and how CAP plays a key role in enabling the SAP Business AI platform as the underlying platform for the Autonomous Enterprise. He also explained the importance of CAP in the age of AI.

Recording link

Keynote by Daniel Hutzel
In his keynote, Daniel shared an overview of the biggest CAP achievements since the last reCAP, including AI-related topics.

Recording link

Main Track Sessions in Audimax

CAP Tools – What’s New and Hot by Christian Georgi
A tour through the latest and greatest in CAP tooling, including:

`cds repl` with queries
Debugging apps on Kyma
CDS Project outline in Visual Studio Code
CAP in browser

Recording link

Optimizing CAP Performance with Data Replication and Caching – Part II by Mike Zaschka
As a follow-up to last year’s talk on cds-caching, this session broadened the view to the full landscape of caching, replication, and federation strategies in the CAP ecosystem. Mike walked through a curated selection of solutions and offered practical guidance on which approach fits which scenario.

Recording link

AI-Assisted Development of CAP Apps by Daniel Schlachter and Stefan Rudi
A look at the CAP MCP development server, which gives AI coding assistants direct access to CAP documentation improving code quality in tools like Claude Code and GitHub Copilot.

Recording link

Expressions and Abstractions – Two Developer Superpowers in CAP by Patrice Bender and DJ Adams
A demonstration of two powerful CAP affordances: expressions (what they are, how to use them, and why they matter) and mocking (letting you iterate fast on data, auth, messaging, and remote services).

Recording link

CAP Plugins: Latest and Greatest by Max Eckert, Dries Van Vaerenbergh, Matthis Vansteenhuyse, and Lisa Julia Nebel
CAP plugins dramatically simplify integration with SAP BTP services. This session demystified the plugin model and spotlighted the enhanced attachments plugin, the renovated change tracking plugin, a new notifications plugin for Java, and the new SAP Build Process Automation plugin.

Recording link

Plug, Connect, Play: CAP Integration Made Effortless by Ram Prasad GS and Bilal El-Massoudi
An introduction to cap-connect, a production-ready, open-source CAP plugin from Aarini Consulting that brings first-class connection management to any CAP application. The talk also showcased how cap-connect powers Prodsphere, Aarini’s own CAP-based product.

Recording link

Production GenAI in CAP: Beyond the Demo by Moudhaffer Azizi
This session explored the architecture behind a production-grade CAP application on SAP BTP that uses RAG to analyse custom ABAP code against Clean Core standards. The session highlighted the journey from a single prompt to a resilient solution orchestrating 14 AI-powered operations.

Recording link

Beyond Vibe Coding: Engineering Deterministic CAP Applications with SDD by Maximilian Hartig and Abdulbasıt Gülşen
A live "0-to-1" walkthrough of Spec-Driven Development using the open-source Spec Kit in Visual Studio Code to transform a raw business requirement into a CAP application.

Recording link

From Click-Ops to Code-Ops (Terraform) by Nicholas Arefta
Nicholas demonstrated how to use Terraform to deploy multitenant apps on SAP BTP. He demonstrated provisioning of a Provider subaccount, deploying a multi-tenant application and onboarding a Subscriber completely hands-free.

Recording link

Custom Business Logic with Predefined Extension Points – Using CDS-Oyster by Nick Josipovic and Konrad Koschel
Together with Subscription Billing and Cloud Foundation, Nick and Konrad built an extensive Extension Box using CAP and the CDS-Oyster Code Sandbox enabling secure code extensions in a complex cloud environment.

Recording link

Implementing Runtime Plugins in CAP Java by Joshua Mitchell
Joshua demonstrated in his live session how to program a basic soft delete plugin for CAP Java using annotations, the IntelliJ debugger, and an expression evaluator.

Recording link

Side Track Sessions in W1/W2

Building Code-Based AI Agents with CAP and UI5: From Concept to Production by Wouter Lemaire

Using the Smart Monitoring Agent (previously demonstrated at SAP TechEd) as a real-world example, Wouter showed how to build intelligent, code-based AI agents by combining SAP AI Core with CAP and UI5. The session covered the complete journey from development to deployment.

Recording link

Building AI-enabled Applications with CAP by Max Eckert, Simon Engel, Markus Riedinger, and Peter W. Szabo

An overview of how CAP is evolving to meet the AI era including: exposing CAP services as endpoints for AI agents, leveraging the CAP AI plugin, exploring additional features, and building intelligent, code-driven agents.

Recording link

Building a CAP Application with Latest Best Practices and AI by Lukas Theis, Johannes Vogt, Marc Becker, and Robin de Silva Jayasinghe

A practical, end-to-end walkthrough from idea to production-ready CAP app, combining proven CAP architecture patterns with AI-assisted workflows.

Recording link

Declarative Programming Patterns in CAP - Less Code, More Power by Adrian Görler, Robin de Silva Jayasinghe, and Vitaly Kozyura

A look at how declarative mechanisms in CAP such as calculated elements, annotation-based constraints (e.g. @assert, @assert.range, @assert.format), and field control help to reduce custom code. The session also covered how status transition flows help reducing the need for custom validation logic while ensuring data integrity.

Recording link

Update from the cap-js-community - Experience the latest additions to CAP by Oliver Klemenz

A focused technical update on the latest enhancements in the cap-js-community, with a deep dive into the WebSocket modules and the newly introduced common utilities module.

Recording link

AI-Assisted Security Hardening of CAP Applications by Matthias Braun

Matthias showed how AI-powered tools can help identify authorization gaps, generate comprehensive security tests, and detect attack vectors. This significantly reduces the effort required to build and maintain secure CAP applications.

Recording link

Event Queues Scheduling by Sebastian Van Syckel, Dietrich Mostowoj, Thomas Bonk, and Lars Plessing
A deep dive into Transactional Event Queues, which allow scheduling of events and background tasks for asynchronous, exactly-once processing with strong resilience.

Recording link

Automated Testing with HANA Cloud by Armin Hatting
Armin presented practical approaches to integrating database-supported testing in CAP applications, setting up realistic test environments, and ensuring the functionality of SAP HANA Cloud native logic.

Recording link

Did you know about infix filters and projection functions? by Nico Schoenteich

A live-coding overview of infix filters and projection functions (Node.js) and how they were applied in a recent project to reduce custom service.

Recording link

Thank You

A huge thank-you to all speakers, attendees, and community members who made reCAP 2026 such an inspiring day. 🙌 The energy, the ideas, and the conversations are exactly what makes the CAP community special.

If you missed any session, use the recording links above to catch up.

We look forward to seeing how you use what you learned at reCAP 2026. If you have any feedback, please let us know.

Happy coding! 😊

SAP CodeJam HANA AI at Code:Connect 2026-07 Recap

2026-07-22T23:09:29.621000+02:00

During Code:Connect 2026, we held an SAP CodeJam event in St. Leon-Rot, Germany. The event focused on exploring the foundations of AI applications with the SAP HANA Cloud: Vector Engine and Knowledge Graph Engine.

Thanks to all participants who joined, and also to @ChristophMorgen for his presentation!

I hope exercises were helpful, insightful, and -- sometimes -- entertaining 🤓

This CodeJam was an introductory for the HANA Tech Con happening the same week, where I had the pleasure to co-present with my fellow dev advocates (from the image above): @noravonthenen

...and @thomas_jung

Would you like to host such an SAP CodeJam in your location?

Working with BDC in the Autonomous Enterprise: The Enterprise Architect Perspective

2026-07-23T16:03:16.546000+02:00

AI will not replace enterprise architecture. It will depend on it.

For enterprise architects working with SAP Business Data Cloud (BDC), that single idea reframes the Autonomous Enterprise. Your mandate hasn’t changed. You still ensure the structural integrity of the enterprise data and application landscape through governed architectures, trusted semantics, and scalable integration. What has changed is who, and what, your architecture now serves.

With the SAP Business AI Platform (BAIP), AI agents join humans and applications as first-class consumers of the enterprise landscape. Your architecture becomes the semantic contract that binds all three to a shared source of truth.

What stays the same

Your core responsibilities are intact:

Designing end-to-end data flows across SAP Datasphere, SAP BW, SAP Analytics Cloud, SAP HANA Cloud, SAP Master Data Governance, and SAP Reltio.
Defining integration patterns across SAP and non-SAP systems.
Establishing standards for identity, security, lineage, lifecycle, scalability, resilience, cost, and compliance.

None of this is sidelined. In fact, it matters more, because AI now depends on it.

What changes in practice

The biggest shift: AI agents are now architectural consumers, not just applications or users.

In the Autonomous Enterprise, AI agents reason over governed BDC data products rather than loosely curated datasets. That means every architectural decision how data products are modeled, how integrations are designed, how governance is enforced, directly shapes how trustworthy, safe, and scalable AI-driven decisions will be.

Every well-designed data product and reusable integration pattern now serves both human and AI consumption, dramatically reducing the risk of shadow AI built on ungoverned data.

How AI-integrated architecture works with BDC

AI-driven execution does not bypass your architectural blueprints. It builds on them.

BDC empowers AI agents across the enterprise by serving as the AI knowledge core. Data products defined in BDC, sourced from SAP applications, BW objects, or Datasphere models. They carry business meaning, lineage, and access rules. BAIP uses these data products as its trusted context layer for AI reasoning and action. When AI agents generate recommendations, trigger workflows, or execute processes, they do so against this governed semantic layer and are designed to inherit the same authorizations and policies you defined.

For enterprise architects, this means designing architectures that expose data products as reusable, governed, AI-consumable assets, not just as feeds into dashboards or reports.

A simple example: a governed revenue KPI data product defined once in SAP Datasphere can be consumed by a planner in SAP Analytics Cloud, a Fiori app, and a BAIP agent that triggers an approval workflow, all using the same semantics and authorizations.

Trust, governance, and risk

One of the biggest enterprise AI challenges is trust: How do you ensure AI operates within the same boundaries as human users and applications?

In the Autonomous Enterprise architecture, trust is enforced by design. Because AI agents rely on the same BDC-managed semantics, master data, and access policies used by human consumers. AI outputs are designed to reflect the same KPI logic, hierarchies, filters, and authorization rules. Governance applies consistently whether the consumer is a dashboard, a planner, a business application, or an AI agent.

The result: fewer parallel governance frameworks for AI and compliance, auditability, and risk controls that extend naturally into the AI layer, keeping the architecture defensible under regulatory scrutiny.

How does this map to BDC components

For enterprise architects, the strategic component mapping is clear.

SAP Datasphere is the semantic backbone of the Autonomous Enterprise, the primary place where governed data products, semantic models, and business context are defined and exposed, providing authoritative definitions for process-critical KPIs and data domains.
SAP Analytics Cloud remains the primary consumption layer for analysis, planning, and AI-assisted insight generation.
SAP Master Data Governance ensures master data consistency underpins analytical, transactional, and AI-driven outcomes.
SAP Reltio delivers an AI-ready, context-rich, trusted data foundation harmonizing across SAP and non-SAP landscapes.
SAP HANA Cloud provides a high-performance data foundation that supports advanced analytical queries, vector processing, and low-latency access for applications and AI agents.
The embedded Databricks partnership, complemented by Snowflake interoperability, extends BDC with open lakehouse capabilities, enabling AI/ML workloads and unstructured data processing via zero-copy Delta Sharing.
The SAP Business AI Platform (BAIP) uses these components as its trusted context layer, enabling AI agents to reason and act on governed enterprise data.

Together, these components form the trusted architectural foundation on which the Autonomous Enterprise runs.

What to focus on now

As an enterprise architect, the most valuable preparation is not evaluating new AI tools. It is strengthening the foundation AI will rely on. Concretely, invest in:

Well-designed data products with clear ownership, lineage, and reusability.
Consistent semantics across SAP and non-SAP domains.
Federated governance models that scale across business units.
Integration patterns that treat data products as reusable APIs, not point-to-point pipelines.
Identity, access, and policy frameworks that extend seamlessly to AI agents.
Openness and interoperability leveraging Delta Sharing and open formats to future-proof your architecture.

The stronger your foundation today, the more reliable and trustworthy your AI-driven decisions will be tomorrow.

The takeaway

The Autonomous Enterprise does not replace enterprise architecture with AI. It makes enterprise architecture the governed foundation on which trustworthy AI depends.
The architectures you design, govern, and evolve no longer serve only people and applications. They shape how AI itself reasons and acts across the enterprise.

Continue the Conversation

Join the Enterprise Architecture community to share patterns, discuss AI-integrated designs, and see how peers are evolving their BDC architectures.

Useful resources:

Type	Convention	Example
Class	PascalCase	`bdc:WorkCenter`, `bdc:Customer`
Relationship (ObjectProperty)	camelCase, verb phrase	`bdc:producesProduct`, `bdc:hasAddress`
Attribute (DatatypeProperty)	camelCase	`bdc:country`, `bdc:customerID`
Instance	`ClassName_identifier`	`bdc:WorkCenter_Z_ASM3`, `bdc:Customer_0001000010`

File	What it contains	Example
Ontology file	Class and property definitions (the blueprint)	`bdc:Supplier a owl:Class`
R2RML mapping file	The rule "take a row from this table (or the result of this SQL query) and convert it to instance data according to that blueprint"	`Row of SUPPLIER_MASTER = instance of bdc:Supplier`
Instance data	The actual data triples	`bdc:Supplier_S001 a bdc:Supplier ; bdc:name "ACME"`

Option	How the bridge is handled	Pros	Cons
(a) Direct connect (flatten)	The bridge entity is not persisted in the KG; only the endpoints (A → C) are connected as a 1-hop relationship	The KG stays clean, multi-hop does not pollute visualization, SPARQL is simple	Information carried by the bridge itself is invisible in the KG
(b) Persist the bridge as a node	The bridge entity is loaded into the KG as a separate class (A → B → C)	The bridge's attributes (plant, period, priority) become explorable via SPARQL	Node count increases, intermediate nodes appear in visualizations