Extend embeddings docs

guides/databases/vector-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.
+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/>
@@ -112,3 +112,64 @@ let similarIncidents = await SELECT.from('Incidents')
 ```
 :::
 
+## 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 SAP HANA Vector Functions](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-sql-reference-guide/vector-functions) {.learn-more}
+
+### cosine_similarity
+```
+cosine_similarity(vector1, vector2) → number
+```
+Measures vector similarity (range: -1 to 1). Returns 1 for identical vectors, 0 for orthogonal vectors, -1 for opposite vectors.
+
+### l2distance
+```
+l2distance(vector1, vector2) → number
+```
+Calculates Euclidean distance between two vectors. Returns 0 for identical vectors.
+
+### l2normalize
+```
+l2normalize(vector) → vector
+```
+Normalizes a vector to a standard length of 1 by scaling all components proportionally.
+
+### vector_embedding
+```
+vector_embedding(text, text_type, model_name) → vector
+vector_embedding(text, text_type, model_name, remote_source) → vector
+```
+Generates vector embeddings from text.
+
+**Parameters:**
+- `text` - Input text to embed
+- `text_type` - `'DOCUMENT'` (for storing content) or `'QUERY'` (for search queries)
+- `model_name` - Model identifier (database-specific)
+- `remote_source` (optional) - Remote source configuration for external embedding services (SAP HANA only)
+
+**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.
+- **PostgreSQL:** No default implementation. Application developers must define their own `vector_embedding` function.
+
+## Database-Specific Considerations
+
+### 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
+  CREATE EXTENSION IF NOT EXISTS vector;
+  ```
+- Vectors stored in native `vector` type
+- `vector_embedding()` SQL function uses hash-based algorithm for testing. Override the SQL function to use real embedding services in production.
+- For Node.js, the `pgvector` npm package is only required when you need to read vector columns from query results. If you only pass vectors as parameters (for example, in WHERE clauses or function arguments), the package is not needed: `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)
+
+[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}
+
+