Extend embeddings docs - #2788
Conversation
| ::: info Local Testing with H2 and SQLite | ||
| On H2 and SQLite the `CQL.vectorEmbedding` function is emulated to support local testing. | ||
| ::: info Local Testing with SQLite and PostgreSQL | ||
| SAP HANA supports all vector functions including the `vector_embedding` function with real AI models. PostgreSQL supports vector functions when the pgvector extension is created, but does not support the `vector_embedding` function natively. A hash-based `vector_embedding` function is provided for both SQLite and PostgreSQL to avoid issues and crashes during development, but it is strongly recommended to override this function with a reasonable custom or third-party implementation for production use. |
There was a problem hiding this comment.
Where did the h2 reference go ?
What is the purpose of mentioning that SAP HANA works in an info section ?
This comment mentions that for Postgres a hash version is delivered, but this is not currently the case.
We should probably add the information that for Postgres production the customers have to define their own vector_embedding function.
There was a problem hiding this comment.
changed. my hope was that compiler will deliver hash function soon.
| ``` | ||
| l2normalize(vector) → vector | ||
| ``` | ||
| Normalizes a vector to unit length. |
There was a problem hiding this comment.
unit length being -1 to 1 ?
|
|
||
| **Database Implementation:** | ||
| - **HANA:** Uses real AI models (SAP built-in models or external remote sources) | ||
| - **SQLite & PostgreSQL:** Hash-based deterministic implementation for testing. Can be overridden by application developers to use external embedding services. |
There was a problem hiding this comment.
Postgres function not currently automatically deployed.
There was a problem hiding this comment.
changed. again, I hoped for soon compiler change
| ## Database-Specific Considerations | ||
|
|
||
| ### SQLite | ||
| - Vector functions implemented as JavaScript UDFs |
There was a problem hiding this comment.
I don't think we should document this internal details.
There was a problem hiding this comment.
removed sqlite section from here
| ### SQLite | ||
| - Vector functions implemented as JavaScript UDFs | ||
| - Vectors stored as JSON strings | ||
| - No external dependencies required |
There was a problem hiding this comment.
Sounds a bit weird when the future state is not mentioned.
| - Vector functions implemented as JavaScript UDFs | ||
| - Vectors stored as JSON strings | ||
| - No external dependencies required | ||
| - `vector_embedding()` uses hash-based algorithm for testing. Override the JavaScript function to use real embedding services in production. |
There was a problem hiding this comment.
@cap-js/sqlite is not meant to be used for production.
| - `vector_embedding()` uses hash-based algorithm for testing. Override the JavaScript function to use real embedding services in production. | ||
|
|
||
| ### PostgreSQL | ||
| - Requires creating the [pgvector extension](https://github.com/pgvector/pgvector) in the database: |
There was a problem hiding this comment.
not just creating it is also required that the Postgres instance that they use already has the plugin binaries included.
| ``` | ||
| - 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, optional `pgvector` npm package for type registration: `npm install pgvector` |
There was a problem hiding this comment.
Are the vector types optional for the client ? I guess if people run queries like:
SELECT * FROM Books WHERE cosine_similarity(description, vector_embedding(?, 'QUERY')) > 0.8Then the ? will be a simple string. The client would not actually need to have the vector type support unless they explicitly query for the vector type.
| - `vector_embedding()` supports built-in SAP models: | ||
| - `SAP_NEB.20240715` (German, English, Spanish, French, Portuguese - 768 dimensions) | ||
| - `SAP_GXY.20250407` (All above + Italian, Japanese, Chinese - 768 dimensions) | ||
| - Can use external remote sources (Azure OpenAI, SAP AI Core) as optional 4th parameter |
There was a problem hiding this comment.
I think it would be better to exclude the specifics. So that the official SAP HANA help docs can be used as their source of truth directly instead. Otherwise we have to somehow know what models HANA has released in all possible SAP HANA versions.
| ``` | ||
| ::: | ||
|
|
||
| ## Vector Functions |
There was a problem hiding this comment.
We should consider simply referencing to the official SAP HANA documentation for these functions. As we are required to provide an equivalent implementation of those functions.
There was a problem hiding this comment.
As we are providing only subset of HANA functions, I list them here, but for more details i added link to HANA page.
2 participants
Docs for cap-js/cds-dbs#1676