From 5022697b7b81f8b7a55684f14602bf994066000e Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 4 Sep 2026 13:32:44 +0200
Subject: [PATCH 1/2] Embeddings: Stored calculated elements + localized

---
 guides/ai/embeddings.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/guides/ai/embeddings.md b/guides/ai/embeddings.md
index f4b1c110e..eb9d867bc 100644
--- a/guides/ai/embeddings.md
+++ b/guides/ai/embeddings.md
@@ -42,8 +42,14 @@ extend Incidents with {
 }
 ```
 
-:::tip Prefer calculated elements for vector embeddings
-If the database calculates vector embeddings on write it automatically regenerates the embedding if the input data changes.
+:::tip Calculated elements for vector embeddings
+If the database calculates vector embeddings [on-write](../../cds/cdl#on-write) it automatically regenerates the embedding if the input data changes, keeping them consistent without extra application code.
+
+Be aware of the trade-off: the embedding is computed synchronously as part of the insert/update, which adds latency to every write. In high-throughput scenarios, computing embeddings asynchronously in a batch job (see [Generate Embeddings Programmatically](#generate-embeddings-programmatically)) can offer better write throughput.
+:::
+
+::: warning Embedding localized elements
+A stored ([on-write](../../cds/cdl#on-write)) calculated element **cannot** reference [localized](../uis/localized-data) elements. Instead, embed the default language and use a **multilingual embedding model** so that queries in other languages still match.
 :::
 
 ::: info Local Testing with H2 and SQLite

From 8ad6c2e23368e4003de959679700a6a2f80bfdcd Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 4 Sep 2026 15:04:54 +0200
Subject: [PATCH 2/2] outbox

---
 guides/ai/embeddings.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/guides/ai/embeddings.md b/guides/ai/embeddings.md
index eb9d867bc..7ed3f97cc 100644
--- a/guides/ai/embeddings.md
+++ b/guides/ai/embeddings.md
@@ -43,9 +43,9 @@ extend Incidents with {
 ```
 
 :::tip Calculated elements for vector embeddings
-If the database calculates vector embeddings [on-write](../../cds/cdl#on-write) it automatically regenerates the embedding if the input data changes, keeping them consistent without extra application code.
+Database-calculated embeddings [on-write](../../cds/cdl#on-write) stay automatically consistent — the database regenerates the embedding whenever the input data changes, with no extra application code.
 
-Be aware of the trade-off: the embedding is computed synchronously as part of the insert/update, which adds latency to every write. In high-throughput scenarios, computing embeddings asynchronously in a batch job (see [Generate Embeddings Programmatically](#generate-embeddings-programmatically)) can offer better write throughput.
+The trade-off is synchronous latency on every write. For SAP HANA native [NLP](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/creating-text-embeddings-with-nlp-51eb170d038d4099a9bbb85c08fda888) models, this overhead is usually acceptable. For remote embedding services, or multitenant applications — computing embeddings asynchronously using the [Transactional Outbox](./events/event-queues) can offer better write throughput — if eventual consistency is acceptable.
 :::
 
 ::: warning Embedding localized elements