fix: Move DB agnostic sections out of `sqlite` database guide #973

patricebender · 2024-06-03T12:23:28Z

With this change, Common Operators and Common Functions have been moved from the sqlite guide to the generic database guide.

The function list is now including all functions which are supported by all cap-js/dbs.

Todos:

align with Java colleagues, I think we can make this section a shared one for both stacks
how to document the to-be-expected return types?

Also, it would be nice to remove the disclaimer only supported in runtime queries, but for that we first need compiler support for the functions as well as for the operators.

``` > q = SELECT`from ${Books} { ID, title} where ID != null` > q.toSQL() { sql: `SELECT json_insert('{}','$."ID"',ID,'$."title"',title) as _json_ FROM (SELECT Books.ID,Books.title FROM sap_capire_bookshop_Books as Books WHERE Books.ID is not NULL)`, values: [] } ``` but for non-`null` comparisons, `!=` is translated to `<>`: ``` > q = SELECT`from ${Books} { ID, title} where ID != 207` > q.toSQL() { sql: `SELECT json_insert('{}','$."ID"',ID,'$."title"',title) as _json_ FROM (SELECT Books.ID,Books.title FROM sap_capire_bookshop_Books as Books WHERE Books.ID <> ?)`, values: [ 207 ] } ```

guides/databases-sqlite.md

guides/databases.md

patricebender · 2024-06-13T11:27:37Z

ping @johannes-vogel @stewsk

johannes-vogel · 2024-06-20T12:57:06Z

does that also apply to java?

renejeglinsky · 2024-07-11T07:22:48Z

does that also apply to java?

@johannes-vogel Do you mean we'd need the equivalent docs for Java when moving those docs in the common guide?

@patricebender Is there anything I can support you with?

patricebender · 2024-07-11T07:40:36Z

does that also apply to java?

@johannes-vogel Do you mean we'd need the equivalent docs for Java when moving those docs in the common guide?

@patricebender Is there anything I can support you with?

I think the "common operators" section must be moved to the generic part of the db guide, I would like to hear the POs opinions here. From my side, this change is fine (I only need to apply the suggestion from Bob).

johannes-vogel · 2024-07-12T09:09:29Z

does that also apply to java?

@johannes-vogel Do you mean we'd need the equivalent docs for Java when moving those docs in the common guide?
@patricebender Is there anything I can support you with?

I think the "common operators" section must be moved to the generic part of the db guide, I would like to hear the POs opinions here. From my side, this change is fine (I only need to apply the suggestion from Bob).

I was simply wondering whether this is node specific or also applicable for java. at the moment it's tagged as node specific. in general, fine for me:)

guides/databases.md

renejeglinsky · 2024-09-23T10:00:30Z

@MattSchur @agoerler Could you please check this PR? It's about moving a topic and also what is probably Node/Java specific (or not!)

agoerler · 2024-09-23T10:56:33Z

guides/databases.md

+### Standard Operators {.impl .node}

+The database services guarantee identical behavior of these operators:
+
+* `==`, `=` — with `=` null being translated to `is null`
+* `!=`, `<>` — with `!=` translated to `IS NOT` in SQLite, or to `IS DISTINCT FROM` in standard SQL, or to an equivalent polyfill in SAP HANA
+* `<`, `>`, `<=`, `>=`, `IN`, `LIKE` — are supported as is in standard SQL
+* `||` — concatenation operator
+
+In particular, the translation of `!=` to `IS NOT` in SQLite — or to `IS DISTINCT FROM` in standard SQL, or to an equivalent polyfill in SAP HANA — greatly improves the portability of your code.
+
+> These operators are available for runtime queries, but not in CDS files.


The behaviour of the operators is not standardized in CAP and different in CAP Java. There is an open BLI to get to a common understanding: https://github.tools.sap/cap/dev/issues/909

The corresponding documentation for CAP Java is here: https://pages.github.tools.sap/cap/docs/java/working-with-cql/query-api#predicates

agoerler · 2024-09-23T11:00:45Z

guides/databases.md

+> These operators are available for runtime queries, but not in CDS files.
+
+
+### Functions Mappings for Runtime Queries {.impl .node}


We have a general agreement on the semantic of the functions: https://github.tools.sap/cap/dev/issues/1111

We could create a table here to capture which functions are supported by CAP Java and which by CAP Node.js. SImilar to what @patricebender compiled here: https://github.tools.sap/cap/dev/issues/1111#issuecomment-7092917

@renejeglinsky As a first step, this list contains all functions which are supported by the node.js runtime. For months this list has been outdated and it was not at the right place of the documentation (those functions are supported by all db services, not only sqlite).

@agoerler what do you think about adding the functions which are supported by the java runtime ({.impl .java}) in a similar fashion? As we already went over the list, I could also contribute this list (assuming the semantics of the functions are the same).

I would probably refrain from using a table in the documentation. The list of supported functions could be toggled instead, for better readability.

I think adding the functions using the toggle would be great. Thanks Patrice!

@patricebender As this section is toggled for node, should we include the table for Java in this PR or do this as a follow-up?

I'd be fine with following up in another change to add a java toggle here 👍

agoerler · 2024-09-23T11:02:47Z

guides/databases.md

+> For the SAP HANA functions, both usages are allowed: all-lowercase as given above, as well as all-uppercase.
+
+
+### Session Variables {.impl .node}


There is a completely different API in CAP Java.

As this is toggled for Node we could provide the same section for Java. Would be really nice to have it in this PR but if capacity doesn't allow for that, I don't think that would be a blocker for this change, or?

guides/databases.md

agoerler · 2024-10-17T08:05:38Z

guides/databases.md

+
+### Functions Mappings for Runtime Queries {.impl .node}
+
+A specified set of standard functions is supported in a **database-agnostic**, hence portable way, and translated to database-specific variants or polyfills.


Another thing to consider. These standard functions are not only database-agnostic but even data-source-agnostic. They can also be used with remote OData. Moreover, they there names, semantics and parameters are closer to OData then to SQL. Maybe we should move this section out of database.md and rather to a CDS QL section.

@johannes-vogel What do you think?

patricebender · 2024-11-06T12:52:38Z

@stewsk @johannes-vogel could you kindly review

agoerler · 2024-11-06T18:17:55Z

@agoerler what do you think about adding the functions which are supported by the java runtime ({.impl .java}) in a similar fashion?

For CAP Java, the set of supported functions is documented here:

scalar functions: https://cap.cloud.sap/docs/java/working-with-cql/query-api#scalar-functions
predicated: https://cap.cloud.sap/docs/java/working-with-cql/query-api#predicate-functions

As mentioned earlier, these functions can be used on the DBs but also in remote OData consumption. We could add a link in an ({.impl .java}) variant. Maybe in a follow-up PR).

patricebender · 2024-11-07T13:17:19Z

@renejeglinsky how can I fix the broken anchor links mentioned in the build:

in: /releases/jun24
Unresolved hash link: /guides/databases-sqlite #standard-operators
Unresolved hash link: /guides/databases-sqlite #standard-functions
Unresolved hash link: /guides/databases-sqlite #sap-hana-functions

I can't find them in the repository :(

…973) * fix: `!= null` is translated to `is not null` but `!= <xpr>` is not ``` > q = SELECT`from ${Books} { ID, title} where ID != null` > q.toSQL() { sql: `SELECT json_insert('{}','$."ID"',ID,'$."title"',title) as _json_ FROM (SELECT Books.ID,Books.title FROM sap_capire_bookshop_Books as Books WHERE Books.ID is not NULL)`, values: [] } ``` but for non-`null` comparisons, `!=` is translated to `<>`: ``` > q = SELECT`from ${Books} { ID, title} where ID != 207` > q.toSQL() { sql: `SELECT json_insert('{}','$."ID"',ID,'$."title"',title) as _json_ FROM (SELECT Books.ID,Books.title FROM sap_capire_bookshop_Books as Books WHERE Books.ID <> ?)`, values: [ 207 ] } ``` * Update guides/databases-sqlite.md

patricebender requested review from renejeglinsky and smahati as code owners June 3, 2024 12:23

patricebender commented Jun 3, 2024

View reviewed changes

guides/databases-sqlite.md Outdated Show resolved Hide resolved

Update guides/databases-sqlite.md

1d6c640

patricebender requested a review from BobdenOs June 3, 2024 12:25

patricebender enabled auto-merge (squash) June 3, 2024 12:28

patricebender added 2 commits June 3, 2024 16:02

Merge branch 'main' into patricebender-patch-1

2874202

adapt and move common sections to generic db section

62bdcd5

patricebender changed the title ~~fix: != null is translated to is not null but != <xpr> is not~~ fix: Move DB agnostic sections out of sqlite database guide Jun 6, 2024

patricebender requested a review from johannes-vogel June 6, 2024 13:23

patricebender commented Jun 6, 2024

View reviewed changes

guides/databases.md Outdated Show resolved Hide resolved

patricebender commented Jun 6, 2024

View reviewed changes

guides/databases.md Outdated Show resolved Hide resolved

Merge branch 'main' into patricebender-patch-1

148a278

renejeglinsky reviewed Jun 6, 2024

View reviewed changes

guides/databases.md Outdated Show resolved Hide resolved

renejeglinsky and others added 2 commits June 6, 2024 20:27

Update guides/databases.md

1af530b

Merge branch 'main' into patricebender-patch-1

bb219c8

patricebender requested review from renejeglinsky and stewsk June 13, 2024 11:27

patricebender added 3 commits July 23, 2024 18:09

move sections, apply some fixes

9e7124c

Merge branch 'main' into patricebender-patch-1

c3e8b43

more improvements

7898981

patricebender commented Sep 3, 2024

View reviewed changes

guides/databases.md Outdated Show resolved Hide resolved

patricebender added 2 commits September 3, 2024 15:20

Update guides/databases.md

a6e84e4

Merge branch 'main' into patricebender-patch-1

60fc7a8

patricebender requested a review from danjoa September 3, 2024 13:21

agoerler reviewed Sep 23, 2024

View reviewed changes

patricebender commented Sep 23, 2024

View reviewed changes

guides/databases.md Outdated Show resolved Hide resolved

patricebender added 3 commits October 7, 2024 15:44

dont mention concat operator

93287be

improve RT only disclaimer

fff118c

Merge branch 'main' into patricebender-patch-1

3ecf2d2

agoerler reviewed Oct 17, 2024

View reviewed changes

Merge branch 'main' into patricebender-patch-1

c977243

danjoa approved these changes Nov 6, 2024

View reviewed changes

stewsk approved these changes Nov 6, 2024

View reviewed changes

renejeglinsky approved these changes Nov 6, 2024

View reviewed changes

Merge branch 'main' into patricebender-patch-1

5072fd6

Merge branch 'main' into patricebender-patch-1

535608f

patricebender merged commit 3d19fbc into main Nov 8, 2024
4 checks passed

patricebender deleted the patricebender-patch-1 branch November 8, 2024 05:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: Move DB agnostic sections out of `sqlite` database guide #973

fix: Move DB agnostic sections out of `sqlite` database guide #973

patricebender commented Jun 3, 2024 •

edited

Loading

patricebender commented Jun 13, 2024

johannes-vogel commented Jun 20, 2024

renejeglinsky commented Jul 11, 2024

patricebender commented Jul 11, 2024

johannes-vogel commented Jul 12, 2024

renejeglinsky commented Sep 23, 2024

agoerler Sep 23, 2024

agoerler Sep 23, 2024

patricebender Sep 23, 2024

renejeglinsky Sep 23, 2024

renejeglinsky Oct 17, 2024

patricebender Oct 17, 2024

agoerler Sep 23, 2024

renejeglinsky Oct 17, 2024

agoerler Oct 17, 2024

renejeglinsky Oct 17, 2024

patricebender commented Nov 6, 2024

agoerler commented Nov 6, 2024 •

edited

Loading

patricebender commented Nov 7, 2024

		> These operators are available for runtime queries, but not in CDS files.


		### Functions Mappings for Runtime Queries {.impl .node}

		> For the SAP HANA functions, both usages are allowed: all-lowercase as given above, as well as all-uppercase.


		### Session Variables {.impl .node}


		### Functions Mappings for Runtime Queries {.impl .node}

		A specified set of standard functions is supported in a database-agnostic, hence portable way, and translated to database-specific variants or polyfills.

fix: Move DB agnostic sections out of sqlite database guide #973

fix: Move DB agnostic sections out of sqlite database guide #973

Conversation

patricebender commented Jun 3, 2024 • edited Loading

patricebender commented Jun 13, 2024

johannes-vogel commented Jun 20, 2024

renejeglinsky commented Jul 11, 2024

patricebender commented Jul 11, 2024

johannes-vogel commented Jul 12, 2024

renejeglinsky commented Sep 23, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

patricebender commented Nov 6, 2024

agoerler commented Nov 6, 2024 • edited Loading

patricebender commented Nov 7, 2024

fix: Move DB agnostic sections out of `sqlite` database guide #973

fix: Move DB agnostic sections out of `sqlite` database guide #973

patricebender commented Jun 3, 2024 •

edited

Loading

agoerler commented Nov 6, 2024 •

edited

Loading