Skip to content

Node.js: Vector Embeddings #2837

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
sjvans wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Node.js: Vector Embeddings #2837

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cefadbe
rm java only
sjvans Aug 26, 2026
258c0ca
docs: Node.js ai-sqlite embeddings in vector-embeddings guide
sjvans Aug 26, 2026
a186b59
docs: use in-database vector_embedding in Node.js similarity example
sjvans Aug 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 18 additions & 13 deletions guides/databases/vector-embeddings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,9 @@ 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.
:::

> [!warning] Java only and <Beta/>
> The `vector_embedding` function is currently in beta and only supported by the CAP Java runtime.
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. <Beta/>
:::

[Learn more about Vector Embeddings in CAP Java](../../java/cds-data#vector-embeddings) {.learn-more}

Expand Down Expand Up @@ -100,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`
```
:::

Expand Down Expand Up @@ -139,11 +136,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. <Beta/>
- **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. <Beta/>
```sh
npm add @cap-js/ai onnxruntime-node@1.20.1
```
<Config>cds.requires.db: ai-sqlite</Config>

### 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
Expand Down
Loading