From dd5dbf5cd4372f5128ab55e68f351f6f73d168a6 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Wed, 15 Apr 2026 13:54:19 +0200
Subject: [PATCH 01/18] Move vector embeddings out of HANA section

---
 guides/databases/vector-embeddings.md | 81 +++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 guides/databases/vector-embeddings.md

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
new file mode 100644
index 000000000..7973c1c30
--- /dev/null
+++ b/guides/databases/vector-embeddings.md
@@ -0,0 +1,81 @@
+---
+label: Vector Embeddings
+---
+# Vector Embeddings
+
+Vector embeddings let you add semantic search, recommendations, and generative AI features to your CAP application. Embeddings are numeric arrays that represent the meaning of unstructured data (text, images, etc.), making it possible to compare and search for items that are semantically related to each other or a user query.
+
+## Choose an Embedding Model
+
+Choose an embedding model that fits your use case and data (for example english or multilingual text). The model determines the number of dimensions of the resulting output vector. Check the documentation of the respective embedding model for details.
+
+Use the [SAP Generative AI Hub](https://community.sap.com/t5/technology-blogs-by-sap/how-sap-s-generative-ai-hub-facilitates-embedded-trustworthy-and-reliable/ba-p/13596153) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
+
+## Add Embeddings to Your CDS Model
+Use the `cds.Vector` type in your CDS model to store embeddings on SAP HANA Cloud. Set the dimension to match your embedding model (for example, 1536 embedding dimensions for OpenAI *text-embedding-3-small*).
+
+   ```cds
+   entity Books : cuid {
+     title       : String(111);
+     description : LargeString;
+     embedding   : Vector(1536); // adjust dimensions to embedding model
+   }
+   ```
+
+## Generate Embeddings
+Use an embedding model to convert your data (for example, book descriptions) into vectors. The [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) makes it easy to call SAP AI Core services to generate these embeddings.
+
+:::details Example using SAP Cloud SDK for AI
+```Java
+var aiClient = OpenAiClient.forModel(OpenAiModel.TEXT_EMBEDDING_3_SMALL);
+var response = aiClient.embedding(
+   new OpenAiEmbeddingRequest(List.of(book.getDescription())));
+book.setEmbedding(CdsVector.of(response.getEmbeddingVectors().get(0)));
+```
+:::
+
+## Query for Similarity
+At runtime, use SAP HANA's built-in vector functions to search for similar items. For example, find books with embeddings similar to a user question:
+
+::: code-group
+```Java [Java]
+// Compute embedding for user question
+var request = new OpenAiEmbeddingRequest(List.of("How to use vector embeddings in CAP?"));
+CdsVector userQuestion = CdsVector.of(
+ aiClient.embedding(request).getEmbeddingVectors().get(0));
+
+// Compute similarity between user question and book embeddings
+var similarity = CQL.cosineSimilarity( // computed on SAP HANA
+  CQL.get(Books.EMBEDDING), userQuestion);
+
+// Find Books related to user question ordered by similarity
+hana.run(Select.from(BOOKS).limit(10)
+  .columns(b -> b.ID(), b -> b.title(), b -> similarity.as("similarity"))
+  .orderBy(b -> b.get("similarity").desc())
+);
+```
+
+```js [Node.js]
+const response = await new AzureOpenAiEmbeddingClient(
+ 'text-embedding-3-small'
+).run({
+ input: 'How to use vector embeddings in CAP?'
+});
+
+const questionEmbedding = response.getEmbedding();
+let similarBooks = await SELECT.from('Books')
+  .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.9`;
+```
+:::
+
+:::tip Evolve embeddings with your model
+Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
+:::
+
+:::tip Use SAP Cloud SDK for AI
+Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access to embedding models and large language models (LLMs) from [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core).
+:::
+
+Learn more about the [SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) or the [SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
+
+[Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}

From 80e593027a212be7805b8293877490c3827ac7e8 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Wed, 15 Apr 2026 13:55:25 +0200
Subject: [PATCH 02/18] Remove vector embeddings section from HANA guide

---
 guides/databases/hana.md | 80 ----------------------------------------
 1 file changed, 80 deletions(-)

diff --git a/guides/databases/hana.md b/guides/databases/hana.md
index 4bda1e0c3..ac78a3650 100644
--- a/guides/databases/hana.md
+++ b/guides/databases/hana.md
@@ -261,86 +261,6 @@ See the [Deploying to Cloud](../deploy/index.md) guide for information about how
 
 The HANA Service provides dedicated support for native SAP HANA features as follows.
 
-### Vector Embeddings
-
-Vector embeddings let you add semantic search, recommendations, and generative AI features to your CAP application. Embeddings are numeric arrays that represent the meaning of unstructured data (text, images, etc.), making it possible to compare and search for items that are semantically related to each other or a user query.
-
-#### Choose an Embedding Model
-
-Choose an embedding model that fits your use case and data (for example english or multilingual text). The model determines the number of dimensions of the resulting output vector. Check the documentation of the respective embedding model for details.
-
-Use the [SAP Generative AI Hub](https://community.sap.com/t5/technology-blogs-by-sap/how-sap-s-generative-ai-hub-facilitates-embedded-trustworthy-and-reliable/ba-p/13596153) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
-
-#### Add Embeddings to Your CDS Model
-Use the `cds.Vector` type in your CDS model to store embeddings on SAP HANA Cloud. Set the dimension to match your embedding model (for example, 1536 embedding dimensions for OpenAI *text-embedding-3-small*).
-
-   ```cds
-   entity Books : cuid {
-     title       : String(111);
-     description : LargeString;
-     embedding   : Vector(1536); // adjust dimensions to embedding model
-   }
-   ```
-
-#### Generate Embeddings
-Use an embedding model to convert your data (for example, book descriptions) into vectors. The [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) makes it easy to call SAP AI Core services to generate these embeddings.
-
-:::details Example using SAP Cloud SDK for AI
-```Java
-var aiClient = OpenAiClient.forModel(OpenAiModel.TEXT_EMBEDDING_3_SMALL);
-var response = aiClient.embedding(
-   new OpenAiEmbeddingRequest(List.of(book.getDescription())));
-book.setEmbedding(CdsVector.of(response.getEmbeddingVectors().get(0)));
-```
-:::
-
-#### Query for Similarity
-At runtime, use SAP HANA's built-in vector functions to search for similar items. For example, find books with embeddings similar to a user question:
-
-::: code-group
-```Java [Java]
-// Compute embedding for user question
-var request = new OpenAiEmbeddingRequest(List.of("How to use vector embeddings in CAP?"));
-CdsVector userQuestion = CdsVector.of(
- aiClient.embedding(request).getEmbeddingVectors().get(0));
-
-// Compute similarity between user question and book embeddings
-var similarity = CQL.cosineSimilarity( // computed on SAP HANA
-  CQL.get(Books.EMBEDDING), userQuestion);
-
-// Find Books related to user question ordered by similarity
-hana.run(Select.from(BOOKS).limit(10)
-  .columns(b -> b.ID(), b -> b.title(), b -> similarity.as("similarity"))
-  .orderBy(b -> b.get("similarity").desc())
-);
-```
-
-```js [Node.js]
-const response = await new AzureOpenAiEmbeddingClient(
- 'text-embedding-3-small'
-).run({
- input: 'How to use vector embeddings in CAP?'
-});
-
-const questionEmbedding = response.getEmbedding();
-let similarBooks = await SELECT.from('Books')
-  .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.9`;
-```
-:::
-
-:::tip Evolve embeddings with your model
-Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
-:::
-
-:::tip Use SAP Cloud SDK for AI
-Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access to embedding models and large language models (LLMs) from [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core).
-:::
-
-Learn more about the [SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) or the [SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
-
-[Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}
-
-
 ### Geospatial Functions
 
 CDS supports the special syntax for SAP HANA geospatial functions:

From 98623ff38140a598c94565887d93c52c45d990aa Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Wed, 15 Apr 2026 13:56:22 +0200
Subject: [PATCH 03/18] Add Vector Embeddings link to database menu

---
 guides/databases/_menu.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/guides/databases/_menu.md b/guides/databases/_menu.md
index ca989779d..cdbfd2514 100644
--- a/guides/databases/_menu.md
+++ b/guides/databases/_menu.md
@@ -10,3 +10,4 @@
  ## [ PostgreSQL ](postgres.md)
 # [ Schema Evolution ](schema-evolution.md) 
 # [ Performance Guide ](performance.md)
+# [ Vector Embeddings ](vector-embeddings.md)

From 2742cce4058440457f9e70048904b787204c6294 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Wed, 15 Apr 2026 17:03:32 +0200
Subject: [PATCH 04/18] Update link for vector embeddings documentation

---
 java/cds-data.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/java/cds-data.md b/java/cds-data.md
index 4ff869296..a2a9dad33 100644
--- a/java/cds-data.md
+++ b/java/cds-data.md
@@ -330,7 +330,7 @@ Map data can be nested and may contain nested maps and lists, which are serializ
 
 ## Vector Embeddings <Beta /> { #vector-embeddings }
 
-In CDS [vector embeddings](../guides/databases/hana#vector-embeddings) are stored in elements of type `cds.Vector`:
+In CDS [vector embeddings](../guides/databases/vector-embeddings) are stored in elements of type `cds.Vector`:
 
 ```cds
 entity Books : cuid { // [!code focus]

From d98f9a5034cbfd5ec72b3922f42e371f8dc00ed6 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Wed, 15 Apr 2026 17:41:20 +0200
Subject: [PATCH 05/18] revise

---
 guides/databases/vector-embeddings.md | 64 ++++++++++++++++-----------
 1 file changed, 37 insertions(+), 27 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 7973c1c30..a38e84d83 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -3,27 +3,36 @@ label: Vector Embeddings
 ---
 # Vector Embeddings
 
-Vector embeddings let you add semantic search, recommendations, and generative AI features to your CAP application. Embeddings are numeric arrays that represent the meaning of unstructured data (text, images, etc.), making it possible to compare and search for items that are semantically related to each other or a user query.
+Vector embeddings convert unstructured content (text, images, etc.) into numeric vectors that encode semantic meaning. Comparing these vectors enables semantic search, recommendations, and enhanced generative AI features in your CAP application, for example retrieving related records, ranking results by relevance, or augmenting prompts for LLMs.
 
 ## Choose an Embedding Model
 
 Choose an embedding model that fits your use case and data (for example english or multilingual text). The model determines the number of dimensions of the resulting output vector. Check the documentation of the respective embedding model for details.
 
-Use the [SAP Generative AI Hub](https://community.sap.com/t5/technology-blogs-by-sap/how-sap-s-generative-ai-hub-facilitates-embedded-trustworthy-and-reliable/ba-p/13596153) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
+Use the [SAP Generative AI Hub](https://www.sap.com/products/artificial-intelligence/generative-ai-hub.html) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
 
 ## Add Embeddings to Your CDS Model
-Use the `cds.Vector` type in your CDS model to store embeddings on SAP HANA Cloud. Set the dimension to match your embedding model (for example, 1536 embedding dimensions for OpenAI *text-embedding-3-small*).
+Use the `cds.Vector` type in your CDS model to store embeddings on SAP HANA Cloud. Set the dimension to match your embedding model (for example, 768 embedding dimensions for *SAP_GXY.20250407*).
 
-   ```cds
-   entity Books : cuid {
-     title       : String(111);
-     description : LargeString;
-     embedding   : Vector(1536); // adjust dimensions to embedding model
-   }
-   ```
+```cds
+extend Incidents with {
+  embedding : cds.Vector(768);
+}
+```
 
 ## Generate Embeddings
-Use an embedding model to convert your data (for example, book descriptions) into vectors. The [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) makes it easy to call SAP AI Core services to generate these embeddings.
+Use an embedding model to convert your data (for example, incident summaries) into vectors.
+
+To generate vector embeddings on write in SAP HANA, you can use the [vector_embedding](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-sql-reference-guide/vector-embedding-function-vector) function as calculated element [on-write](../../cds/cdl#on-write) with embedding models from [SAP HANA NLP](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/creating-text-embeddings-with-nlp-51eb170d038d4099a9bbb85c08fda888) or a configured remote source from SAP AI Core:
+
+```cds
+extend Incidents with {
+  embedding : cds.Vector(768) = vector_embedding(
+       summary, 'DOCUMENT', 'SAP_GXY.20250407') stored;
+}
+```
+
+Alternatively, you can compute vector embeddings in your application layer using the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) to call SAP AI Core services for generating embeddings.
 
 :::details Example using SAP Cloud SDK for AI
 ```Java
@@ -35,35 +44,36 @@ book.setEmbedding(CdsVector.of(response.getEmbeddingVectors().get(0)));
 :::
 
 ## Query for Similarity
-At runtime, use SAP HANA's built-in vector functions to search for similar items. For example, find books with embeddings similar to a user question:
+At runtime, use SAP HANA's built-in vector functions to search for similar items. For example, find incidents that are relevant to a user question:
 
 ::: code-group
 ```Java [Java]
 // Compute embedding for user question
-var request = new OpenAiEmbeddingRequest(List.of("How to use vector embeddings in CAP?"));
-CdsVector userQuestion = CdsVector.of(
- aiClient.embedding(request).getEmbeddingVectors().get(0));
-
-// Compute similarity between user question and book embeddings
-var similarity = CQL.cosineSimilarity( // computed on SAP HANA
-  CQL.get(Books.EMBEDDING), userQuestion);
-
-// Find Books related to user question ordered by similarity
-hana.run(Select.from(BOOKS).limit(10)
-  .columns(b -> b.ID(), b -> b.title(), b -> similarity.as("similarity"))
-  .orderBy(b -> b.get("similarity").desc())
-);
+var query = CQL.val(
+  "Any incidents with solar inverters this month? How were they resolved?");
+var embedding = CQL.vectorEmbedding(query, QUERY, "SAP_GXY.20250407");
+
+// Compute similarity between user question and incident embeddings
+var similarity = CQL.cosineSimilarity(CQL.get(Incidents.EMBEDDING), embedding);
+
+// Find Incidents related to user question ordered by relevance
+Select.from(INCIDENTS)
+   .columns(i -> similarity.times(100).as("relevance"), 
+            i -> i.ID(), i -> i.title(), i -> i.summary(), i -> i.date())
+   .where(i -> similarity.gt(minSimilarity))
+   .orderBy(i -> i.get("relevance").desc());
+```
 ```
 
 ```js [Node.js]
 const response = await new AzureOpenAiEmbeddingClient(
  'text-embedding-3-small'
 ).run({
- input: 'How to use vector embeddings in CAP?'
+ input: 'Any incidents with solar inverters this month? How were they resolved?'
 });
 
 const questionEmbedding = response.getEmbedding();
-let similarBooks = await SELECT.from('Books')
+let similarIncidents = await SELECT.from('Incidents')
   .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.9`;
 ```
 :::

From a6194badd3bdf1a11295a3b5f1d17fdfa88d83f6 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 09:24:54 +0200
Subject: [PATCH 06/18] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Co-authored-by: Adrian Görler <adrian.goerler@sap.com>
---
 guides/databases/vector-embeddings.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index a38e84d83..7ef49ed83 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -3,7 +3,7 @@ label: Vector Embeddings
 ---
 # Vector Embeddings
 
-Vector embeddings convert unstructured content (text, images, etc.) into numeric vectors that encode semantic meaning. Comparing these vectors enables semantic search, recommendations, and enhanced generative AI features in your CAP application, for example retrieving related records, ranking results by relevance, or augmenting prompts for LLMs.
+Vector embeddings convert unstructured content (text, images, etc.) into numeric vectors that encode semantics (meaning). Comparing these vectors enables semantic search, recommendations, and enhanced generative AI features in your CAP application, for example retrieving related records, ranking results by relevance, or augmenting prompts for LLMs.
 
 ## Choose an Embedding Model
 
@@ -12,7 +12,7 @@ Choose an embedding model that fits your use case and data (for example english
 Use the [SAP Generative AI Hub](https://www.sap.com/products/artificial-intelligence/generative-ai-hub.html) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
 
 ## Add Embeddings to Your CDS Model
-Use the `cds.Vector` type in your CDS model to store embeddings on SAP HANA Cloud. Set the dimension to match your embedding model (for example, 768 embedding dimensions for *SAP_GXY.20250407*).
+Use the built-in CDL [Vector](../cds/types) type in your CDS model to store embeddings. Set the vector dimensions to match the embedding model (for example, 768 for *SAP_GXY.20250407*).
 
 ```cds
 extend Incidents with {
@@ -23,6 +23,8 @@ extend Incidents with {
 ## Generate Embeddings
 Use an embedding model to convert your data (for example, incident summaries) into vectors.
 
+### Generate Embeddings on the Database
+
 To generate vector embeddings on write in SAP HANA, you can use the [vector_embedding](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-sql-reference-guide/vector-embedding-function-vector) function as calculated element [on-write](../../cds/cdl#on-write) with embedding models from [SAP HANA NLP](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/creating-text-embeddings-with-nlp-51eb170d038d4099a9bbb85c08fda888) or a configured remote source from SAP AI Core:
 
 ```cds
@@ -32,6 +34,10 @@ extend Incidents with {
 }
 ```
 
+:::info beta
+The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
+:::
+
 Alternatively, you can compute vector embeddings in your application layer using the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) to call SAP AI Core services for generating embeddings.
 
 :::details Example using SAP Cloud SDK for AI
@@ -44,14 +50,14 @@ book.setEmbedding(CdsVector.of(response.getEmbeddingVectors().get(0)));
 :::
 
 ## Query for Similarity
-At runtime, use SAP HANA's built-in vector functions to search for similar items. For example, find incidents that are relevant to a user question:
+At runtime, use vector functions to search for similar items. For example, find incidents that are relevant to a user question:
 
 ::: code-group
 ```Java [Java]
 // Compute embedding for user question
 var query = CQL.val(
   "Any incidents with solar inverters this month? How were they resolved?");
-var embedding = CQL.vectorEmbedding(query, QUERY, "SAP_GXY.20250407");
+var embedding = CQL.vectorEmbedding(query, TextType.QUERY, "SAP_GXY.20250407");
 
 // Compute similarity between user question and incident embeddings
 var similarity = CQL.cosineSimilarity(CQL.get(Incidents.EMBEDDING), embedding);
@@ -60,7 +66,7 @@ var similarity = CQL.cosineSimilarity(CQL.get(Incidents.EMBEDDING), embedding);
 Select.from(INCIDENTS)
    .columns(i -> similarity.times(100).as("relevance"), 
             i -> i.ID(), i -> i.title(), i -> i.summary(), i -> i.date())
-   .where(i -> similarity.gt(minSimilarity))
+   .where(i -> similarity.gt(0.75f))
    .orderBy(i -> i.get("relevance").desc());
 ```
 ```
@@ -74,7 +80,7 @@ const response = await new AzureOpenAiEmbeddingClient(
 
 const questionEmbedding = response.getEmbedding();
 let similarIncidents = await SELECT.from('Incidents')
-  .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.9`;
+  .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.75`;
 ```
 :::
 

From 6c3fdb0cdfaeda483a1257a2e0e0d0906e59b82d Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 09:25:24 +0200
Subject: [PATCH 07/18] Apply suggestions from code review

Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
---
 guides/databases/vector-embeddings.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 7ef49ed83..1b25859f4 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -38,6 +38,8 @@ extend Incidents with {
 The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
 :::
 
+### Generate Embeddings Programmatically
+
 Alternatively, you can compute vector embeddings in your application layer using the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) to call SAP AI Core services for generating embeddings.
 
 :::details Example using SAP Cloud SDK for AI

From 30361946c2a33a56d1f85ee74136804b1520bbb6 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 09:36:02 +0200
Subject: [PATCH 08/18] vector_embedding

Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
---
 guides/databases/vector-embeddings.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 1b25859f4..ef04c5d60 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -29,13 +29,19 @@ To generate vector embeddings on write in SAP HANA, you can use the [vector_embe
 
 ```cds
 extend Incidents with {
-  embedding : cds.Vector(768) = vector_embedding(
-       summary, 'DOCUMENT', 'SAP_GXY.20250407') stored;
+  @cds.api.ignore
+  embedding : Vector(768) = vector_embedding( 
+    'Title: ' || title || ', Summary: ' || summary, 
+    'DOCUMENT', 'SAP_GXY.20250407'
+  ) stored; 
 }
 ```
 
-:::info beta
-The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
+> [!warning] Java only and <Beta/>
+> The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
+
+::: info Local Testing with H2 and SQLite
+On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing.
 :::
 
 ### Generate Embeddings Programmatically

From 7581070646f7dad7c91af4b547e253fded8e1376 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 09:44:31 +0200
Subject: [PATCH 09/18] Move AI SDK tip

Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
---
 guides/databases/vector-embeddings.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index ef04c5d60..037296bbb 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -57,6 +57,12 @@ book.setEmbedding(CdsVector.of(response.getEmbeddingVectors().get(0)));
 ```
 :::
 
+:::tip Use SAP Cloud SDK for AI
+Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access to embedding models and large language models (LLMs) from [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core).
+:::
+
+Learn more about the [SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) or the [SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
+
 ## Query for Similarity
 At runtime, use vector functions to search for similar items. For example, find incidents that are relevant to a user question:
 
@@ -96,10 +102,5 @@ let similarIncidents = await SELECT.from('Incidents')
 Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
 :::
 
-:::tip Use SAP Cloud SDK for AI
-Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access to embedding models and large language models (LLMs) from [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core).
-:::
-
-Learn more about the [SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) or the [SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
 
 [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}

From 9f69d2e35f4e8cbc8ae4a0fd00f83dd384a759fd Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 09:46:31 +0200
Subject: [PATCH 10/18] Apply suggestions from code review

Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
---
 guides/databases/vector-embeddings.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 037296bbb..273774634 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -21,7 +21,11 @@ extend Incidents with {
 ```
 
 ## Generate Embeddings
-Use an embedding model to convert your data (for example, incident summaries) into vectors.
+Use an embedding model to convert your data (for example, incident titles and summaries) into vectors.
+
+:::tip Evolve embeddings with your model
+Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
+:::
 
 ### Generate Embeddings on the Database
 
@@ -98,9 +102,6 @@ let similarIncidents = await SELECT.from('Incidents')
 ```
 :::
 
-:::tip Evolve embeddings with your model
-Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
-:::
 
 
 [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}

From 691fafb8e007797bb60cd0d4c87ec045da430663 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 10:13:32 +0200
Subject: [PATCH 11/18] Apply suggestion from @MattSchur

---
 guides/databases/vector-embeddings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 273774634..925430bd5 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -16,7 +16,7 @@ Use the built-in CDL [Vector](../cds/types) type in your CDS model to store embe
 
 ```cds
 extend Incidents with {
-  embedding : cds.Vector(768);
+  embedding : Vector(768);
 }
 ```
 

From f64e9b10c079496f5cffecc6e54b54e9570628dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adrian=20G=C3=B6rler?= <adrian.goerler@sap.com>
Date: Fri, 24 Apr 2026 11:41:21 +0200
Subject: [PATCH 12/18] cleanup

---
 guides/databases/vector-embeddings.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 925430bd5..ce24f5940 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -23,7 +23,7 @@ extend Incidents with {
 ## Generate Embeddings
 Use an embedding model to convert your data (for example, incident titles and summaries) into vectors.
 
-:::tip Evolve embeddings with your model
+:::warning Evolve embeddings with your model
 Store embeddings when you create or update your data. Regenerate embeddings if you change your embedding model.
 :::
 
@@ -41,6 +41,10 @@ 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.
+:::
+
 > [!warning] Java only and <Beta/>
 > The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
 
@@ -87,7 +91,6 @@ Select.from(INCIDENTS)
    .where(i -> similarity.gt(0.75f))
    .orderBy(i -> i.get("relevance").desc());
 ```
-```
 
 ```js [Node.js]
 const response = await new AzureOpenAiEmbeddingClient(

From 1890886fdc8b458231762ab17c6cb0d5d88a24e4 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 12:59:42 +0200
Subject: [PATCH 13/18] learn-more

---
 guides/databases/vector-embeddings.md | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index ce24f5940..c3aa871ef 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -45,13 +45,15 @@ extend Incidents with {
 If the database calculates vector embeddings on write it automatically regenerates the embedding if the input data changes.
 :::
 
-> [!warning] Java only and <Beta/>
-> The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
-
 ::: info Local Testing with H2 and SQLite
 On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing.
 :::
 
+> [!warning] Java only and <Beta/>
+> The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
+
+[Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}
+
 ### Generate Embeddings Programmatically
 
 Alternatively, you can compute vector embeddings in your application layer using the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) to call SAP AI Core services for generating embeddings.
@@ -105,6 +107,3 @@ let similarIncidents = await SELECT.from('Incidents')
 ```
 :::
 
-
-
-[Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}

From 17897a7db38ab4a491c6cbea4eaa6569b8371a06 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 14:16:43 +0200
Subject: [PATCH 14/18] Apply suggestion from @MattSchur

---
 guides/databases/vector-embeddings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index c3aa871ef..300384e9f 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -74,7 +74,7 @@ Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access
 Learn more about the [SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) or the [SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
 
 ## Query for Similarity
-At runtime, use vector functions to search for similar items. For example, find incidents that are relevant to a user question:
+At runtime, use vector functions to search for similar items. In a Retrieval-Augmented Generation (RAG) scenario, for example to enhance the context of a user query for the LLM to answer the query, compute the vector embedding of the user query and use `CQL.cosineSimilarity` to find incidents that are relevant to a user question and can be given to the LLM to answer the question.
 
 ::: code-group
 ```Java [Java]

From 5c7560133a651da01489e89ef72110a8d186dbf8 Mon Sep 17 00:00:00 2001
From: Matthias Schur <107557548+MattSchur@users.noreply.github.com>
Date: Fri, 24 Apr 2026 17:25:09 +0200
Subject: [PATCH 15/18] Apply suggestion from @MattSchur

---
 guides/databases/vector-embeddings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 300384e9f..406a39edc 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -90,7 +90,7 @@ var similarity = CQL.cosineSimilarity(CQL.get(Incidents.EMBEDDING), embedding);
 Select.from(INCIDENTS)
    .columns(i -> similarity.times(100).as("relevance"), 
             i -> i.ID(), i -> i.title(), i -> i.summary(), i -> i.date())
-   .where(i -> similarity.gt(0.75f))
+   .where(i -> similarity.gt(0.75))
    .orderBy(i -> i.get("relevance").desc());
 ```
 

From 94ac41112ff932d67e4c7f16db0026cbb5e4dbb5 Mon Sep 17 00:00:00 2001
From: Mahati Shankar <93712176+smahati@users.noreply.github.com>
Date: Mon, 27 Apr 2026 15:01:50 +0200
Subject: [PATCH 16/18] cosmetics

---
 guides/databases/vector-embeddings.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 406a39edc..1b9b4f3d3 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -3,13 +3,13 @@ label: Vector Embeddings
 ---
 # Vector Embeddings
 
-Vector embeddings convert unstructured content (text, images, etc.) into numeric vectors that encode semantics (meaning). Comparing these vectors enables semantic search, recommendations, and enhanced generative AI features in your CAP application, for example retrieving related records, ranking results by relevance, or augmenting prompts for LLMs.
+Vector embeddings convert unstructured content (text, images, and so on) into numeric vectors that encode semantics (meaning). Comparing these vectors enables semantic search, recommendations, and enhanced generative AI features in your CAP application. For example retrieving related records, ranking results by relevance, or augmenting prompts for LLMs.
 
 ## Choose an Embedding Model
 
-Choose an embedding model that fits your use case and data (for example english or multilingual text). The model determines the number of dimensions of the resulting output vector. Check the documentation of the respective embedding model for details.
+Choose an embedding model that fits your use case and data (for example English or multilingual text). The model determines the number of dimensions of the resulting output vector. Check the documentation of the respective embedding model for details.
 
-Use the [SAP Generative AI Hub](https://www.sap.com/products/artificial-intelligence/generative-ai-hub.html) for unified consumption of embedding models and LLMs across different vendors and open source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
+Use the [SAP Generative AI Hub](https://www.sap.com/products/artificial-intelligence/generative-ai-hub.html) for unified consumption of embedding models and LLMs across different vendors and open-source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
 
 ## Add Embeddings to Your CDS Model
 Use the built-in CDL [Vector](../cds/types) type in your CDS model to store embeddings. Set the vector dimensions to match the embedding model (for example, 768 for *SAP_GXY.20250407*).
@@ -74,7 +74,7 @@ Use the [SAP Cloud SDK for AI](https://sap.github.io/ai-sdk/) for unified access
 Learn more about the [SAP Cloud SDK for AI (Java)](https://sap.github.io/ai-sdk/docs/java/getting-started) or the [SAP Cloud SDK for AI (JavaScript)](https://sap.github.io/ai-sdk/docs/js/getting-started) {.learn-more}
 
 ## Query for Similarity
-At runtime, use vector functions to search for similar items. In a Retrieval-Augmented Generation (RAG) scenario, for example to enhance the context of a user query for the LLM to answer the query, compute the vector embedding of the user query and use `CQL.cosineSimilarity` to find incidents that are relevant to a user question and can be given to the LLM to answer the question.
+At runtime, use vector functions to search for similar items. In an example Retrieval-Augmented Generation (RAG) scenario, use `CQL.cosineSimilarity` to enhance the context of a user query for the LLM. First, compute the vector embedding of the user query and use it to find related incidents.
 
 ::: code-group
 ```Java [Java]

From b55c9d0623b38f42b78db6555a2cd9779b2611f4 Mon Sep 17 00:00:00 2001
From: Mahati Shankar <93712176+smahati@users.noreply.github.com>
Date: Mon, 27 Apr 2026 15:16:32 +0200
Subject: [PATCH 17/18] fix broken link

---
 guides/databases/vector-embeddings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md
index 1b9b4f3d3..cb4ebe69f 100644
--- a/guides/databases/vector-embeddings.md
+++ b/guides/databases/vector-embeddings.md
@@ -12,7 +12,7 @@ Choose an embedding model that fits your use case and data (for example English
 Use the [SAP Generative AI Hub](https://www.sap.com/products/artificial-intelligence/generative-ai-hub.html) for unified consumption of embedding models and LLMs across different vendors and open-source models. Check for available models on the [SAP AI Launchpad](https://help.sap.com/docs/ai-launchpad/sap-ai-launchpad-user-guide/models-and-scenarios-in-generative-ai-hub-fef463b24bff4f44a33e98bb1e4f3148#models).
 
 ## Add Embeddings to Your CDS Model
-Use the built-in CDL [Vector](../cds/types) type in your CDS model to store embeddings. Set the vector dimensions to match the embedding model (for example, 768 for *SAP_GXY.20250407*).
+Use the built-in CDL [Vector type](../../cds/types) in your CDS model to store embeddings. Set the vector dimensions to match the embedding model (for example, 768 for *SAP_GXY.20250407*).
 
 ```cds
 extend Incidents with {

From 0a8513bf1754286a894ec4b49d01665749e2bcf8 Mon Sep 17 00:00:00 2001
From: Mahati Shankar <93712176+smahati@users.noreply.github.com>
Date: Mon, 27 Apr 2026 16:09:13 +0200
Subject: [PATCH 18/18] fix links

---
 java/working-with-cql/query-api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/java/working-with-cql/query-api.md b/java/working-with-cql/query-api.md
index d43317e4e..926f2303c 100644
--- a/java/working-with-cql/query-api.md
+++ b/java/working-with-cql/query-api.md
@@ -1643,7 +1643,7 @@ Scalar functions are values that are calculated from other values. This calculat
 
 #### Vector Functions
 
-Vector functions allow you to compute similarity and distance of [vectors](../cds-data.md#vector-embeddings), as well as [vector embeddings](../../guides/databases/hana.md#vector-embeddings) of text data directly in the database.
+Vector functions allow you to compute similarity and distance of [vectors](../cds-data.md#vector-embeddings), as well as [vector embeddings](../../guides/databases/vector-embeddings) of text data directly in the database.
 
 ##### Computing Vector Embeddings in SAP HANA <Beta />
 
@@ -1682,7 +1682,7 @@ On H2 and SQLite, the `vectorEmbedding` function is emulated. You can also use l
 
 ##### Computing Vector Similarity and Distance
 
-You can use the functions, `CQL.cosineSimilarity`, and `CQL.l2Distance` (Euclidean distance) in queries to compute the similarity and distance of vectors. Distance functions are used in use cases such as finding similar items based on [vector embeddings](../../guides/databases/hana.md#vector-embeddings), for example to improve the response of an LLM to a user query. To use vector embeddings in functions, wrap them using `CQL.vector`:
+You can use the functions, `CQL.cosineSimilarity`, and `CQL.l2Distance` (Euclidean distance) in queries to compute the similarity and distance of vectors. Distance functions are used in use cases such as finding similar items based on [vector embeddings](../../guides/databases/vector-embeddings), for example to improve the response of an LLM to a user query. To use vector embeddings in functions, wrap them using `CQL.vector`:
 
 ```Java
 CqnVector vec = CQL.vector(embedding);