Vector Embeddings

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.

Use the SAP Generative AI Hub for unified consumption of embedding models and LLMs across different vendors and open-source models. Check for available models on the SAP AI Launchpad.

Add Embeddings to Your CDS Model

Use the built-in CDL Vector type to store embeddings. Use Vector without specifying a dimension to simplify changing the embedding model. If you specify a vector dimension, make sure it matches the embedding model (for example, 768 for SAP_GXY.20250407).

extend Incidents with {
  embedding : Vector;
}

Generate Embeddings

Use an embedding model to convert your data (for example, incident titles and summaries) into vectors.

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

To generate vector embeddings on write in SAP HANA, you can use the vector_embedding function as calculated element on-write with embedding models from SAP HANA NLP or a configured remote source from SAP AI Core:

extend Incidents with {
  @cds.api.ignore
  embedding : Vector = vector_embedding(
    'Title: ' || title || ', Summary: ' || summary,
    'DOCUMENT', 'SAP_GXY.20250407'
  ) stored;
}

Prefer calculated elements for vector embeddings

If the database calculates vector embeddings on write it automatically regenerates the embedding if the input data changes.

Local Testing with SQLite and H2

On SQLite and H2 the vector_embedding function is emulated for local testing, with optional local ONNX models for semantic embeddings. See SQLite and H2 for setup details.

Beta 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

Generate Embeddings Programmatically

Alternatively, you can compute vector embeddings in your application layer using the SAP Cloud SDK for AI to call SAP AI Core services for generating embeddings.

Example using SAP Cloud SDK for AI

String question = "Are there patterns with overheating solar inverters?";
var request = OrchestrationEmbeddingRequest
                .forModel(TEXT_EMBEDDING_3_SMALL)
                .forInputs(question).asQuery();
OrchestrationEmbeddingResponse response = client.embed(request);
float[] embedding = response.getEmbeddingVectors().get(0);

CdsVector vector = CdsVector.of(embedding);

Use SAP Cloud SDK for AI

Use the SAP Cloud SDK for AI for unified access to embedding models and large language models (LLMs) from SAP AI Core.

Learn more about the SAP Cloud SDK for AI (Java) or the SAP Cloud SDK for AI (JavaScript)

Query for Similarity

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.

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, TextType.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(0.75))
   .orderBy(i -> i.get("relevance").desc());

Node.js

const question =
  'Any incidents with solar inverters this month? How were they resolved?'

// 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.

Learn more about Vector Functions in CAP Java

cosine_similarity

cosine_similarity(vector1, vector2) → number

l2distance

l2distance(vector1, vector2) → number

l2normalize

l2normalize(vector) → vector

vector_embedding

vector_embedding(text, text_type, model_name) → vector
vector_embedding(text, text_type, model_name, remote_source) → vector

Database-Specific Considerations

SQLite and H2

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 models.

ONNX Embeddings Beta

In CAP Java, add a LangChain4j dependency with an ONNX model.

In CAP Node.js, the @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:

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 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 for version requirements, model selection, and configuration.

PostgreSQL

• Requires that the pgvector extension is installed on your PostgreSQL instance. Then create the extension in your database:

  CREATE EXTENSION IF NOT EXISTS vector;

• Vectors stored in native vector type
• CAP provides no built-in vector_embedding implementation. Compute embeddings in your application layer (see 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 uses embedding models from the NLP extension or an SAP AI Core remote source

Learn more about HANA Vector Engine