From cefadbec1f3937ee31de866c90e8467521889bb0 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Wed, 26 Aug 2026 10:06:28 +0200 Subject: [PATCH 01/14] rm java only --- guides/databases/vector-embeddings.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 96344915f6..7b0ffd430e 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -50,9 +50,6 @@ If the database calculates vector embeddings on write it automatically regenerat On H2 and SQLite the `CQL.vectorEmbedding` function is emulated using a hash-based algorithm to support local testing. For PostgreSQL, customers must define their own `vector_embedding` function for both testing and production use. ::: -> [!warning] Java only and -> 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 From 258c0cace6e623aa6e950d1c0feaa45b735fff5d Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Wed, 26 Aug 2026 10:12:05 +0200 Subject: [PATCH 02/14] docs: Node.js ai-sqlite embeddings in vector-embeddings guide --- guides/databases/vector-embeddings.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 7b0ffd430e..23185f12a2 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -48,6 +48,8 @@ If the database calculates vector embeddings on write it automatically regenerat ::: info Local Testing with H2 and SQLite On H2 and SQLite the `CQL.vectorEmbedding` function is emulated using a hash-based algorithm to support local testing. For PostgreSQL, customers must define their own `vector_embedding` function for both testing and production use. + +In CAP Node.js, install the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin and set the database kind to `ai-sqlite` to generate real embeddings locally on SQLite with an [ONNX](https://onnx.ai) model instead of the hash-based emulation. ::: [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more} @@ -136,11 +138,19 @@ vector_embedding(text, text_type, model_name, remote_source) → vector **Database Implementation:** - **HANA:** Uses real AI models (SAP built-in models or external remote sources) -- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. +- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin with the `ai-sqlite` database kind generates real embeddings locally via an [ONNX](https://onnx.ai) model. - **PostgreSQL:** No default implementation. Application developers must define their own `vector_embedding` function. ## Database-Specific Considerations +### SQLite +- Hash-based, deterministic `vector_embedding` implementation by default, suitable for local testing. +- In CAP Node.js, install [`@cap-js/ai`](https://github.com/cap-js/ai) and set the database kind to `ai-sqlite` to generate real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. + ```sh + npm add @cap-js/ai onnxruntime-node@1.20.1 + ``` + cds.requires.db: ai-sqlite + ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: ```sql From a186b59ed9fe860257b708b2c199148af7fd3715 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Wed, 26 Aug 2026 13:29:43 +0200 Subject: [PATCH 03/14] docs: use in-database vector_embedding in Node.js similarity example --- guides/databases/vector-embeddings.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 23185f12a2..80c40106e7 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -99,15 +99,13 @@ Select.from(INCIDENTS) ``` ```js [Node.js] -const response = await new AzureOpenAiEmbeddingClient( - 'text-embedding-3-small' -).run({ - input: 'Any incidents with solar inverters this month? How were they resolved?' -}); - -const questionEmbedding = response.getEmbedding(); -let similarIncidents = await SELECT.from('Incidents') - .where`cosine_similarity(embedding, to_real_vector(${questionEmbedding})) > 0.75`; +const question = + 'Any incidents with solar inverters this month? How were they resolved?' + +// Compute the question's embedding and find related incidents, all in the database +const similarIncidents = await SELECT.from('Incidents').where` + cosine_similarity(embedding, + vector_embedding(${question}, 'QUERY', 'SAP_GXY.20250407')) > 0.75` ``` ::: From 78306bd9da8ec0fd6161b52fb682c7d854ab605e Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Mon, 31 Aug 2026 09:39:41 +0200 Subject: [PATCH 04/14] docs: align ai-sqlite local embeddings with @cap-js/ai#53 Correct the install command (full peer deps), config (nested embedding.model, no default), and framing (experimental, local dev only) for the ai-sqlite database kind. --- guides/databases/vector-embeddings.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 80c40106e7..302f2cd258 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -49,7 +49,7 @@ If the database calculates vector embeddings on write it automatically regenerat ::: info Local Testing with H2 and SQLite On H2 and SQLite the `CQL.vectorEmbedding` function is emulated using a hash-based algorithm to support local testing. For PostgreSQL, customers must define their own `vector_embedding` function for both testing and production use. -In CAP Node.js, install the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin and set the database kind to `ai-sqlite` to generate real embeddings locally on SQLite with an [ONNX](https://onnx.ai) model instead of the hash-based emulation. +In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin adds an `ai-sqlite` database kind that generates real embeddings locally on SQLite with an [ONNX](https://onnx.ai) model. It requires a configured embedding model and is experimental, for local development only. ::: [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more} @@ -143,11 +143,23 @@ vector_embedding(text, text_type, model_name, remote_source) → vector ### SQLite - Hash-based, deterministic `vector_embedding` implementation by default, suitable for local testing. -- In CAP Node.js, install [`@cap-js/ai`](https://github.com/cap-js/ai) and set the database kind to `ai-sqlite` to generate real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. +- In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin adds an `ai-sqlite` database kind that generates real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. It is experimental and intended for local development only. + + Install the plugin with its peer dependencies: ```sh - npm add @cap-js/ai onnxruntime-node@1.20.1 + npm add -D @cap-js/ai @cap-js/sqlite \ + @huggingface/hub @huggingface/tokenizers onnxruntime-node@1.20.1 + ``` + Then set the database kind and configure an embedding model (there's no default): + ```json + { + "cds": { "requires": { "db": { + "kind": "ai-sqlite", + "embedding": { "model": "sentence-transformers/all-MiniLM-L6-v2" } + } } } + } ``` - cds.requires.db: ai-sqlite + On first start, the model is downloaded to `.cds/models` and reused afterwards. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for the full walkthrough and model selection. ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: From 76083ec76b72715a9d3ade5aa2284e31cd299d16 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Wed, 2 Sep 2026 09:15:57 +0200 Subject: [PATCH 05/14] docs: update local SQLite embeddings for merged @cap-js/ai 1.1.0 @cap-js/ai now redirects the standard sqlite (and sqlite:memory) database instead of adding an ai-sqlite kind. A default embedding model exists (pin for stability); requires @sap/cds ^10.1 and @cap-js/sqlite ^3.1. --- guides/databases/vector-embeddings.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 302f2cd258..84329c178b 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -49,7 +49,7 @@ If the database calculates vector embeddings on write it automatically regenerat ::: info Local Testing with H2 and SQLite On H2 and SQLite the `CQL.vectorEmbedding` function is emulated using a hash-based algorithm to support local testing. For PostgreSQL, customers must define their own `vector_embedding` function for both testing and production use. -In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin adds an `ai-sqlite` database kind that generates real embeddings locally on SQLite with an [ONNX](https://onnx.ai) model. It requires a configured embedding model and is experimental, for local development only. +In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally with an [ONNX](https://onnx.ai) model. It is experimental and intended for local development only. ::: [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more} @@ -136,30 +136,30 @@ vector_embedding(text, text_type, model_name, remote_source) → vector **Database Implementation:** - **HANA:** Uses real AI models (SAP built-in models or external remote sources) -- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin with the `ai-sqlite` database kind generates real embeddings locally via an [ONNX](https://onnx.ai) model. +- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally via an [ONNX](https://onnx.ai) model. - **PostgreSQL:** No default implementation. Application developers must define their own `vector_embedding` function. ## Database-Specific Considerations ### SQLite - Hash-based, deterministic `vector_embedding` implementation by default, suitable for local testing. -- In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin adds an `ai-sqlite` database kind that generates real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. It is experimental and intended for local development only. +- In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. It is experimental and intended for local development only. - Install the plugin with its peer dependencies: + Install the plugin and its peer dependencies as dev dependencies. This requires `@sap/cds` `^10.1` and `@cap-js/sqlite` `^3.1`: ```sh - npm add -D @cap-js/ai @cap-js/sqlite \ - @huggingface/hub @huggingface/tokenizers onnxruntime-node@1.20.1 + npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub@^2.15.0 \ + @huggingface/tokenizers@0.1.3 onnxruntime-node@1.20.1 ``` - Then set the database kind and configure an embedding model (there's no default): + No special database kind is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database. A default embedding model is used; pin it explicitly to keep your choice stable while the feature is experimental: ```json { "cds": { "requires": { "db": { - "kind": "ai-sqlite", + "kind": "sqlite", "embedding": { "model": "sentence-transformers/all-MiniLM-L6-v2" } } } } } ``` - On first start, the model is downloaded to `.cds/models` and reused afterwards. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for the full walkthrough and model selection. + On first start, the model is downloaded to `.cds/models` and reused afterwards. In queries, pass `'local'` as the model name to `vector_embedding` to use the configured model. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for the full walkthrough and model selection. ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: From 6a3957e420887feb5ee14ae86e19296eb6ee87f8 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Thu, 3 Sep 2026 10:00:13 +0200 Subject: [PATCH 06/14] docs: document the zero-config default flow for local SQLite embeddings Drop the embedding.model config block and version details; @cap-js/ai works with no configuration (default model). Details in its README. --- guides/databases/vector-embeddings.md | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 84329c178b..ea3b35b88e 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -145,21 +145,12 @@ vector_embedding(text, text_type, model_name, remote_source) → vector - Hash-based, deterministic `vector_embedding` implementation by default, suitable for local testing. - In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. It is experimental and intended for local development only. - Install the plugin and its peer dependencies as dev dependencies. This requires `@sap/cds` `^10.1` and `@cap-js/sqlite` `^3.1`: + Install the plugin with its peer dependencies: ```sh npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub@^2.15.0 \ @huggingface/tokenizers@0.1.3 onnxruntime-node@1.20.1 ``` - No special database kind is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database. A default embedding model is used; pin it explicitly to keep your choice stable while the feature is experimental: - ```json - { - "cds": { "requires": { "db": { - "kind": "sqlite", - "embedding": { "model": "sentence-transformers/all-MiniLM-L6-v2" } - } } } - } - ``` - On first start, the model is downloaded to `.cds/models` and reused afterwards. In queries, pass `'local'` as the model name to `vector_embedding` to use the configured model. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for the full walkthrough and model selection. + No configuration is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database and downloads a default embedding model on first start. In queries, pass `'local'` as the model name to `vector_embedding`. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for version requirements, model selection, and configuration. ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: From 47bbf3532175d50ee2d9b8fdc93e5fcc6131dbdb Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Thu, 3 Sep 2026 11:54:11 +0200 Subject: [PATCH 07/14] Correct SQLite vector_embedding model-name guidance On SQLite the model-name argument to vector_embedding is ignored; the locally configured model is used. The same query runs unchanged on HANA and SQLite, so no 'local' placeholder is needed. --- 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 ea3b35b88e..6eca6dd498 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -150,7 +150,7 @@ vector_embedding(text, text_type, model_name, remote_source) → vector npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub@^2.15.0 \ @huggingface/tokenizers@0.1.3 onnxruntime-node@1.20.1 ``` - No configuration is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database and downloads a default embedding model on first start. In queries, pass `'local'` as the model name to `vector_embedding`. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for version requirements, model selection, and configuration. + No configuration is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database and downloads a default embedding model on first start. The same query runs unchanged on SAP HANA and SQLite: on SQLite the model-name argument to `vector_embedding` is ignored and the locally configured model is used. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for version requirements, model selection, and configuration. ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: From f0533a2213ed7f539672761dc433277b39105a8f Mon Sep 17 00:00:00 2001 From: Matthias Schur <107557548+MattSchur@users.noreply.github.com> Date: Thu, 3 Sep 2026 14:42:18 +0200 Subject: [PATCH 08/14] Refine vector embeddings docs (#2826) --- guides/databases/vector-embeddings.md | 22 ++++++++++++---------- java/working-with-cql/query-api.md | 5 +++-- 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/guides/databases/vector-embeddings.md b/guides/databases/vector-embeddings.md index 6eca6dd498..0fe7851b9c 100644 --- a/guides/databases/vector-embeddings.md +++ b/guides/databases/vector-embeddings.md @@ -47,11 +47,12 @@ If the database calculates vector embeddings on write it automatically regenerat ::: ::: info Local Testing with H2 and SQLite -On H2 and SQLite the `CQL.vectorEmbedding` function is emulated using a hash-based algorithm to support local testing. For PostgreSQL, customers must define their own `vector_embedding` function for both testing and production use. - -In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally with an [ONNX](https://onnx.ai) model. It is experimental and intended for local development only. +On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing. Both runtimes support a hash-based mock embedding as well as local [ONNX](https://onnx.ai) embedding models — CAP Java via LangChain4j, CAP Node.js via the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin (experimental, local development only). ::: +> [!warning] and not supported on PostgreSQL +> The `vector_embedding` function is currently in beta and not supported on PostgreSQL. + [Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more} ### Generate Embeddings Programmatically @@ -111,7 +112,9 @@ const similarIncidents = await SELECT.from('Incidents').where` ## Vector Functions -CAP provides equivalent implementations of vector functions for all supported databases based on the function signatures as defined in SAP HANA: +CAP provides equivalent implementations of vector functions for all supported databases based on the function signatures as defined in SAP HANA. + +[Learn more about Vector Functions in CAP Java](../../java/working-with-cql/query-api#vector-functions) {.learn-more} ### [cosine_similarity](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-sql-reference-guide/cosine-similarity-function-vector) ``` @@ -135,9 +138,9 @@ vector_embedding(text, text_type, model_name, remote_source) → vector ``` **Database Implementation:** -- **HANA:** Uses real AI models (SAP built-in models or external remote sources) -- **SQLite & H2:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally via an [ONNX](https://onnx.ai) model. -- **PostgreSQL:** No default implementation. Application developers must define their own `vector_embedding` function. +- **SAP HANA:** Uses embedding models from the [NLP](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-predictive-analysis-library/natural-language-processing-nlp) extension or an [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core) remote source. +- **SQLite & H2:** Hash-based mock embedding, or local [ONNX](https://onnx.ai) embedding models — in CAP Java via LangChain4j, in CAP Node.js via the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin. +- **PostgreSQL:** Not supported. ## Database-Specific Considerations @@ -158,13 +161,12 @@ vector_embedding(text, text_type, model_name, remote_source) → vector CREATE EXTENSION IF NOT EXISTS vector; ``` - Vectors stored in native `vector` type -- `vector_embedding()` function must be defined by application developers for both testing and production use. +- CAP provides no built-in `vector_embedding` implementation. Compute embeddings in your application layer (see [Generate Embeddings Programmatically](#generate-embeddings-programmatically)) or define your own `vector_embedding` database function. - For Node.js, the `pgvector` npm package is required when reading vector columns from query results or when passing vector values as parameters from the client. It is not needed if vectors are generated entirely within the database using functions like `vector_embedding()`: `npm install pgvector` ### SAP HANA - Native vector engine with built-in support -- Type mapping: `cds.Vector` → `REAL_VECTOR` -- `vector_embedding()` supports built-in SAP models and external remote sources (such as Azure OpenAI, SAP AI Core) +- Type mapping: `cds.Vector` → [REAL_VECTOR](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/real-vector-and-half-vector-data-types) [Learn more about HANA Vector Engine](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide) {.learn-more} diff --git a/java/working-with-cql/query-api.md b/java/working-with-cql/query-api.md index 944627e6e3..8e0a87a18a 100644 --- a/java/working-with-cql/query-api.md +++ b/java/working-with-cql/query-api.md @@ -1681,8 +1681,9 @@ These methods allow you to compute the difference between timestamps: 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. -::: warning Not supported with local MTXS on SQLite -Using vector functions in [stored calculated elements](../../cds/cdl#on-write) with [local MTXS](../../guides/multitenancy/mtxs#test-drive-locally) on SQLite isn't supported. +::: warning Local MTXS on SQLite +Using vector functions in [stored calculated elements](../../cds/cdl#on-write) with [local MTXS](../../guides/multitenancy/mtxs#test-drive-locally) on SQLite +calls the custom functions of the CAP Node.js runtime. Using local [ONNX](https://onnx.ai) embedding models is not yet supported. ::: ##### Computing Vector Embeddings in SAP HANA From f2a8f2c5551fbd7703002b6d095f8ca00914d231 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Thu, 3 Sep 2026 15:37:56 +0200 Subject: [PATCH 09/14] docs: de-duplicate vector embeddings guide (Phase 1) Remove the Database Implementation bullet list that restated the per-DB Database-Specific Considerations subsections; fold the HANA NLP/AI Core note into the SAP HANA subsection; link the local-testing info box down to the SQLite setup. --- guides/ai/embeddings.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/guides/ai/embeddings.md b/guides/ai/embeddings.md index b7c9cc917c..dbb4334a1d 100644 --- a/guides/ai/embeddings.md +++ b/guides/ai/embeddings.md @@ -47,7 +47,7 @@ If the database calculates vector embeddings on write it automatically regenerat ::: ::: info Local Testing with H2 and SQLite -On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing. Both runtimes support a hash-based mock embedding as well as local [ONNX](https://onnx.ai) embedding models — CAP Java via LangChain4j, CAP Node.js via the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin (experimental, local development only). +On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing. Both runtimes support a hash-based mock embedding as well as local [ONNX](https://onnx.ai) embedding models — CAP Java via LangChain4j, CAP Node.js via the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin (experimental, local development only). See [SQLite](#sqlite) below for the CAP Node.js setup. ::: > [!warning] and not supported on PostgreSQL @@ -137,11 +137,6 @@ vector_embedding(text, text_type, model_name) → vector vector_embedding(text, text_type, model_name, remote_source) → vector ``` -**Database Implementation:** -- **SAP HANA:** Uses embedding models from the [NLP](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-predictive-analysis-library/natural-language-processing-nlp) extension or an [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core) remote source. -- **SQLite & H2:** Hash-based mock embedding, or local [ONNX](https://onnx.ai) embedding models — in CAP Java via LangChain4j, in CAP Node.js via the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin. -- **PostgreSQL:** Not supported. - ## Database-Specific Considerations ### SQLite @@ -167,5 +162,6 @@ vector_embedding(text, text_type, model_name, remote_source) → vector ### SAP HANA - Native vector engine with built-in support - Type mapping: `cds.Vector` → [REAL_VECTOR](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide/real-vector-and-half-vector-data-types) +- `vector_embedding` uses embedding models from the [NLP](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-predictive-analysis-library/natural-language-processing-nlp) extension or an [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core) remote source [Learn more about HANA Vector Engine](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-vector-engine-guide) {.learn-more} From cb0bbe0d3759963d620b39cd87d9c45bbb0176dc Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Thu, 3 Sep 2026 15:40:52 +0200 Subject: [PATCH 10/14] docs: cross-link Java and types pages to embeddings guide (Phase 2) --- cds/types.md | 2 +- java/cds-data.md | 2 +- java/working-with-cql/query-api.md | 11 +---------- 3 files changed, 3 insertions(+), 12 deletions(-) diff --git a/cds/types.md b/cds/types.md index 24c28a5613..1ca23aec77 100644 --- a/cds/types.md +++ b/cds/types.md @@ -40,7 +40,7 @@ ANSI SQL types, when deployed to a relational database (concrete mappings to spe ###### Vector Embeddings > [!info] Vector Embeddings -> The `Vector` type is used for vector embeddings, which are a way to represent data (like text, images, etc.) as high-dimensional vectors. Requires SAP HANA Cloud QRC 1/2024, or later, [`@sap/cds` v9.9+](/releases/2026/apr26), and [CAP Java v4.9+](/releases/2026/apr26) to use with H2 or SQLite. +> The `Vector` type stores [vector embeddings](/@external/guides/ai/embeddings). Requires SAP HANA Cloud QRC 1/2024, or later, [`@sap/cds` v9.9+](/releases/2026/apr26), and [CAP Java v4.9+](/releases/2026/apr26) to use with H2 or SQLite. > [!tip] Use Attachments instead of LargeBinary > Consider using _Attachments_, as provided through [the CAP Attachments plugins](/@external/plugins/index#attachments), instead of `LargeBinary` types for user-generated content like documents, images, etc. diff --git a/java/cds-data.md b/java/cds-data.md index eb80aa42a4..b551f367ad 100644 --- a/java/cds-data.md +++ b/java/cds-data.md @@ -332,7 +332,7 @@ Map data can be nested and may contain nested maps and lists, which are serializ In CDS [vector embeddings](../guides/ai/embeddings) are stored in elements of type `Vector`: -CAP Java support the vector type on SAP HANA, as well as H2 and SQLite for local testing. On Postgres (beta) support for vectors requires the [pgvector](https://github.com/pgvector/pgvector) extension. +CAP Java supports the `Vector` type on SAP HANA and, for local testing, on H2 and SQLite; PostgreSQL support is beta. See the guide's [Database-Specific Considerations](../guides/ai/embeddings#database-specific-considerations) for per-database behavior. In CAP Java, vectors are represented by the `CdsVector` type, which allows a unified handling of different vector representations such as `float[]` and `String`: diff --git a/java/working-with-cql/query-api.md b/java/working-with-cql/query-api.md index 98998864dc..ba488f2864 100644 --- a/java/working-with-cql/query-api.md +++ b/java/working-with-cql/query-api.md @@ -1690,16 +1690,7 @@ calls the custom functions of the CAP Node.js runtime. Using local [ONNX](https: CAP Java supports 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 via `CQL.vectorEmbedding` to generate vector embeddings from text data directly in SAP HANA. -To automatically generate vector embeddings on write in the database, you can define a calculated element [on-write](../../cds/cdl#on-write) using the `vector_embedding` function: - -```cds -extend Incidents with { - @cds.api.ignore - embedding : Vector = vector_embedding( - 'title: ' || title || ', summary: ' || summary, - 'DOCUMENT', 'SAP_GXY.20250407') stored; -} -``` +To automatically generate vector embeddings on write, define a calculated element [on-write](../../cds/cdl#on-write) using the `vector_embedding` function — see [Generate Embeddings on the Database](../../guides/ai/embeddings#generate-embeddings-on-the-database) in the guide. In Java queries, use the `CQL.vectorEmbedding` function to compute vector embeddings: From 4b2b34aac3da31eefe52dc51943d66ad4d491079 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Fri, 4 Sep 2026 00:23:30 +0200 Subject: [PATCH 11/14] Apply PR review: SQLite and H2 vector emulation, query-time similarity - Merge SQLite/H2 emulation guidance under a single 'SQLite and H2' section with an ONNX-models subsection (Java LangChain4j + Node.js @cap-js/ai), and reduce the info box to a one-line pointer. - Fix the Query for Similarity Node.js example: repeat the vector_embedding expression in .where (a where clause can't reference a select-list alias) and use the alias only in .orderBy; add a note. - cds-data.md: state vector support for SAP HANA, SQLite and H2. --- guides/ai/embeddings.md | 40 ++++++++++++++++++++++++++-------------- java/cds-data.md | 2 +- 2 files changed, 27 insertions(+), 15 deletions(-) diff --git a/guides/ai/embeddings.md b/guides/ai/embeddings.md index dbb4334a1d..5be0bffd2b 100644 --- a/guides/ai/embeddings.md +++ b/guides/ai/embeddings.md @@ -46,8 +46,8 @@ extend Incidents with { If the database calculates vector embeddings on write it automatically regenerates the embedding if the input data changes. ::: -::: info Local Testing with H2 and SQLite -On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing. Both runtimes support a hash-based mock embedding as well as local [ONNX](https://onnx.ai) embedding models — CAP Java via LangChain4j, CAP Node.js via the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin (experimental, local development only). See [SQLite](#sqlite) below for the CAP Node.js setup. +::: info Local Testing with SQLite and H2 +On SQLite and H2 the `vector_embedding` function is emulated for local testing, with optional local [ONNX](https://onnx.ai) models for semantic embeddings. See [SQLite and H2](#sqlite-and-h2) for setup details. ::: > [!warning] and not supported on PostgreSQL @@ -103,13 +103,19 @@ Select.from(INCIDENTS) const question = 'Any incidents with solar inverters this month? How were they resolved?' -// Compute the question's embedding and find related incidents, all in the database -const similarIncidents = await SELECT.from('Incidents').where` - cosine_similarity(embedding, +// Compute the question's embedding, then find and rank related incidents — all in the database +const similarIncidents = await SELECT.from('Incidents') + .columns`*, cosine_similarity(embedding, + vector_embedding(${question}, 'QUERY', 'SAP_GXY.20250407')) as relevance` + .where`cosine_similarity(embedding, vector_embedding(${question}, 'QUERY', 'SAP_GXY.20250407')) > 0.75` + .orderBy`relevance desc` ``` ::: +> [!note] +> The `vector_embedding(...)` expression is repeated because a `where` clause can't reference a `select`-list alias like `relevance` — only `order by` can. On SQLite this deterministic call is cheap; on SAP HANA, wrap the ranked query in a subquery and filter on the alias to embed the query text only once. + ## Vector Functions CAP provides equivalent implementations of vector functions for all supported databases based on the function signatures as defined in SAP HANA. @@ -139,16 +145,22 @@ vector_embedding(text, text_type, model_name, remote_source) → vector ## Database-Specific Considerations -### SQLite -- Hash-based, deterministic `vector_embedding` implementation by default, suitable for local testing. -- In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate real embeddings locally with an [ONNX](https://onnx.ai) model, without any external service. It is experimental and intended for local development only. +### SQLite and H2 - Install the plugin with its peer dependencies: - ```sh - npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub@^2.15.0 \ - @huggingface/tokenizers@0.1.3 onnxruntime-node@1.20.1 - ``` - No configuration is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database and downloads a default embedding model on first start. The same query runs unchanged on SAP HANA and SQLite: on SQLite the model-name argument to `vector_embedding` is ignored and the locally configured model is used. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for version requirements, model selection, and configuration. +On SQLite and H2, the `vector_embedding` function is emulated using lexical subword embeddings by default. To compute semantic embeddings, use local [ONNX](https://onnx.ai) models. + +#### ONNX Embeddings + +In CAP Java, add a [LangChain4j](https://github.com/langchain4j/langchain4j/tree/main/embeddings) dependency with an ONNX model. + +In CAP Node.js, the [`@cap-js/ai`](https://github.com/cap-js/ai) plugin makes the standard `sqlite` database generate semantic embeddings locally, without any external service. It requires `@sap/cds` `^10.1` and `@cap-js/sqlite` `^3.1`, and is experimental and intended for local development only. Install the plugin with its peer dependencies: + +```sh +npm add -D @cap-js/ai @cap-js/sqlite@^3.1 @huggingface/hub@^2.15.0 \ + @huggingface/tokenizers@0.1.3 onnxruntime-node@1.20.1 +``` + +No configuration is needed — the plugin redirects the standard `sqlite` (and `sqlite:memory`) database and downloads a default embedding model on first start. Both the on-write calculated element from [Generate Embeddings on the Database](#generate-embeddings-on-the-database) and the query-time `vector_embedding` calls then run locally against that model. The same query runs unchanged on SAP HANA and SQLite: on SQLite the model-name argument to `vector_embedding` is ignored and the locally configured model is used. See the [`@cap-js/ai` README](https://github.com/cap-js/ai#local-vector-embeddings-with-sqlite-experimental) for version requirements, model selection, and configuration. ### PostgreSQL - Requires that the [pgvector extension](https://github.com/pgvector/pgvector) is installed on your PostgreSQL instance. Then create the extension in your database: diff --git a/java/cds-data.md b/java/cds-data.md index b551f367ad..8ce4f8b419 100644 --- a/java/cds-data.md +++ b/java/cds-data.md @@ -332,7 +332,7 @@ Map data can be nested and may contain nested maps and lists, which are serializ In CDS [vector embeddings](../guides/ai/embeddings) are stored in elements of type `Vector`: -CAP Java supports the `Vector` type on SAP HANA and, for local testing, on H2 and SQLite; PostgreSQL support is beta. See the guide's [Database-Specific Considerations](../guides/ai/embeddings#database-specific-considerations) for per-database behavior. +CAP Java support the vector type on SAP HANA, as well as SQLite and H2 for local testing. On Postgres (beta) support for vectors requires the [pgvector](https://github.com/pgvector/pgvector) extension. In CAP Java, vectors are represented by the `CdsVector` type, which allows a unified handling of different vector representations such as `float[]` and `String`: From 05ec9c52d06f7829448fccc6c5f0090bfe0bc23b Mon Sep 17 00:00:00 2001 From: sjvans <30337871+sjvans@users.noreply.github.com> Date: Fri, 4 Sep 2026 09:32:53 +0200 Subject: [PATCH 12/14] Update java/cds-data.md Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com> --- 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 8ce4f8b419..eb80aa42a4 100644 --- a/java/cds-data.md +++ b/java/cds-data.md @@ -332,7 +332,7 @@ Map data can be nested and may contain nested maps and lists, which are serializ In CDS [vector embeddings](../guides/ai/embeddings) are stored in elements of type `Vector`: -CAP Java support the vector type on SAP HANA, as well as SQLite and H2 for local testing. On Postgres (beta) support for vectors requires the [pgvector](https://github.com/pgvector/pgvector) extension. +CAP Java support the vector type on SAP HANA, as well as H2 and SQLite for local testing. On Postgres (beta) support for vectors requires the [pgvector](https://github.com/pgvector/pgvector) extension. In CAP Java, vectors are represented by the `CdsVector` type, which allows a unified handling of different vector representations such as `float[]` and `String`: From b13cb0ea58ae247f6c02ed2ea18652bb00d12667 Mon Sep 17 00:00:00 2001 From: Sebastian Van Syckel Date: Fri, 4 Sep 2026 11:45:57 +0200 Subject: [PATCH 13/14] Reword SQLite/H2 default emulation as lexical character-hash vectors Per PR review: 'lexical subword embeddings' oversold the deterministic FNV-1a hash of character n-grams as semantic. Call it what it is. --- guides/ai/embeddings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/embeddings.md b/guides/ai/embeddings.md index 5be0bffd2b..ff653355fe 100644 --- a/guides/ai/embeddings.md +++ b/guides/ai/embeddings.md @@ -147,7 +147,7 @@ vector_embedding(text, text_type, model_name, remote_source) → vector ### SQLite and H2 -On SQLite and H2, the `vector_embedding` function is emulated using lexical subword embeddings by default. To compute semantic embeddings, use local [ONNX](https://onnx.ai) models. +On SQLite and H2, the `vector_embedding` function is emulated using lexical character-hash vectors by default. These capture surface (character-n-gram) overlap, not meaning. To compute semantic embeddings, use local [ONNX](https://onnx.ai) models. #### ONNX Embeddings From 1b02fa992eaefbcccc95d6936574c854a8a4d6ba Mon Sep 17 00:00:00 2001 From: sjvans <30337871+sjvans@users.noreply.github.com> Date: Fri, 4 Sep 2026 11:49:49 +0200 Subject: [PATCH 14/14] Update java/working-with-cql/query-api.md Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com> --- java/working-with-cql/query-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/working-with-cql/query-api.md b/java/working-with-cql/query-api.md index ba488f2864..cb4a679587 100644 --- a/java/working-with-cql/query-api.md +++ b/java/working-with-cql/query-api.md @@ -1683,7 +1683,7 @@ Vector functions allow you to compute similarity and distance of [vectors](../cd ::: warning Local MTXS on SQLite Using vector functions in [stored calculated elements](../../cds/cdl#on-write) with [local MTXS](../../guides/multitenancy/mtxs#test-drive-locally) on SQLite -calls the custom functions of the CAP Node.js runtime. Using local [ONNX](https://onnx.ai) embedding models is not yet supported. +calls the custom functions of the CAP Node.js runtime. ::: ##### Computing Vector Embeddings in SAP HANA