Review databases "compiled to" from CAP Java

guides/databases/cap-level-dbs.md

@@ -24,36 +24,61 @@ This chapter lists standardized operators supported by CAP, and guaranteed to wo
 
 Most native SQL operators are supported in CQL as-is, like these from the SQL92 standard:
 
-- Arithmetic operators: `+`, `-`, `*`, `/`, `%`
+- Arithmetic operators: `+`, `-`, `*`, `/` <sup>1</sup>
 - Comparison operators: `<`, `>`, `<=`, `>=`, `=`, `<>`
 - Logical operators: `AND`, `OR`, `NOT`
 - Other operators: `IN`, `LIKE`, `BETWEEN`, `IS NULL`, `IS NOT NULL`, etc.
 
-In addition, CQL provides some extended operators as described below.
+<sup>1</sup> CAP Node.js additionally supports `%`.
+
+In addition, CQL provides some extended comparison operators as described below.
 
 ### Bivalent `==` and `!=` Operators
 
-CQL supports `==` and `!=` operators as bivalent logic variants for SQL's three-valued logic `=` and `<>`. The differences are as follows:
+CQL supports `==` and `!=` operators as two-valued logic variants for SQL's three-valued logic `=` and `<>`. 
 
-::: code-group
-```SQL [CQL's Two-Valued Logic Operators]
-SELECT 1 == null, 1 != null, null == null, null != null;
---> false, true, true, false
-```
-:::
-::: code-group
-```SQL [SQL's Three-Valued Logic]
-SELECT 1 = null, 1 <> null, null = null, null <> null;
---> null, null, null, null
-```
+::: details 
+The differences are captured in these truth tables:
+
+#### two-valued equality (`==`, CQL)
+
+| == | 1 | 0 | `null` |
+|---|---|---|---|
+| 1 | `true` | `false` | `false` |
+| 0 | `false` | `true` | `false` |
+| `null` | `false` | `false` | `true` |
+
+#### three-valued equality (`=`, CQL & SQL)
+
+| = | 1 | 0 | `null` |
+|---|---|---|---|
+| 1 | `true` | `false` | `unknown` |
+| 0 | `false` | `true` | `unknown` |
+| `null` | `unknown` | `unknown` | `unknown` |
+
+#### two-valued inequality (`!=`, CQL)
+
+| != | 1 | 0 | `null` |
+|---|---|---|---|
+| 1 | `false` | `true` | `true` |
+| 0 | `true` | `false` | `true` |
+| `null` | `true` | `true` | `false` |
+
+#### three-valued inequality (`<>`, CQL & SQL)
+
+| <> | 1 | 0 | `null` |
+|---|---|---|---|
+| 1 | `false` | `true` | `unknown` |
+| 0 | `true` | `false` | `unknown` |
+| `null` | `unknown` | `unknown` | `unknown` |
 :::
 
 In other words:
 
-- CQL's `x == null` -> `true` if `x` is `null`, otherwise `false`
-- CQL's `x != null` -> `false` if `x` is `null`, otherwise `true`
-- SQL's `x = null` -> `null` for all `x` (even if `x` is `null`)
-- SQL's `x <> null` -> `null` for all `x` (even if `x` is not `null`)
+- CQL's `x == null` -> `true` if `x` is `null`
+- CQL's `x != null` -> `true` if `x` is not `null`
+- SQL's `x = null` -> `unknown` for all `x` (even if `x` is `null`)
+- SQL's `x <> null` -> `unknown` for all `x` (even if `x` is not `null`)
 
 A real-world example makes this clearer. Consider this CQL query:
 
@@ -63,11 +88,23 @@ SELECT from Books where genre.name != 'Science Fiction';
 
 The result set includes all books where genre is not 'Science Fiction', including the ones with an unspecified genre. In contrast, using SQL's `<>` operator, the ones with unspecified genre would be excluded.
 
-The CQL behavior is consistent with common programming languages like JavaScript and Java, as well as with OData semantics. It is implemented in database by, the translation of `!=` to `IS NOT` in SQLite, or to `IS DISTINCT FROM` in standard SQL, and to an equivalent polyfill in SAP HANA.
+The behavior of CQL two-valued comparison operators `==` and `!=` is consistent with common programming languages like JavaScript and Java, as well as with the semantics of the OData operators `eq` and `ne`. On the database `==` and `!=` are translated to `IS NOT DISTINCT FROM` and `IS DISTINCT FROM` in standard SQL, to `IS` and `IS NOT` on SQLite, and to an equivalent polyfill on SAP HANA.
 
 > [!tip] Prefer == and !=
 > Prefer using `==` and `!=` in most cases to avoid unexpected `null` results. Only use `=` and `<>` if you _really_ want SQL's three-valued logic behavior.
 
+> [!warning] Semantics of != differs from SQL
+> Be ware that the `!=` operator in CQL uses two-valued logic whereas the `!=` operator uses three-valued logic. 
+
+> [!tip] Avoid using `null` values
+> Declare elements as `not null` where applicable. Or use a non-null value to represent "initial" state.
+
+> [!tip] Compare list values in CAP Java
+> In CAP Java, you may use the comparison operators to compare [list values](../../java/working-with-cql/query-api#list-values) like in this CQL query:
+> ```sql
+> SELECT from Books where (year, month) > (2014, 7)
+> ```
+
 ### Ternary `?:` Operator
 
 CQL supports the ternary conditional operator `condition ? expr1 : expr2`, similar to many programming languages like JavaScript and Java. It evaluates `condition`, and returns the value of `expr1` if `condition` is true, or the value of `expr2` otherwise.
@@ -99,7 +136,6 @@ The following sections list standardized string, numeric, date/time, and aggrega
 > [!important] Function names are case-sensitive
 > The names for standardized functions must be written exactly as listed below. For example, `toUpper` is invalid, while `toupper` is valid. Differently cased names might also work if they match native functions of the specific database, but are not guaranteed to be portable -> always use the exact casing as listed.
 
-
 ### String Functions
 
 - `concat(x,y,...)`
@@ -162,9 +198,7 @@ SELECT firstName || ' ' || lastName as fullName from Authors;
 - `min(x)`, `max(x)`
 - `sum(x)`
 - `count(x)`
-<!-- - `countdistinct(x)` -->
-
-
+- `countdistinct(x)` (CAP Java only)
 
 ## Native Functions
 

guides/databases/cdl-to-ddl.md

@@ -13,7 +13,24 @@ Databases are deployed based on the entity definitions in your CDS models. This
 
 ## Using `cds compile`, ...
 
-CDS compilation to database-specific DDLs is handled by the `cds compile` command, which is part of the [`cds` CLI](../../tools/cds-cli). When you run `cds deploy` or `cds watch`, this command is invoked automatically to generate the necessary DDL statements for your target database.
+CDS compilation to database-specific DDLs is handled by the [`cds compile`](../../tools/cds-cli#cds-compile) command, which is part of the [`cds` CLI](../../tools/cds-cli). When you run `cds deploy` or `cds watch`, this command is invoked automatically to generate the necessary DDL statements for your target database.
+
+In CAP Java, the DDL is generated by the [Maven build](../../java/developing-applications/building#maven-build-options) which uses the [CDS Maven Plugin](../../java/developing-applications/building#cds-maven-plugin)'s [cds](../../java/assets/cds-maven-plugin-site/cds-mojo.html) goal to invoke `cds deploy --dry`.
+
+:::details
+A build configuration to create the DDL specific for H2:
+
+```xml
+<execution>
+  <goals><goal>cds</goal></goals>
+  <configuration>
+    <commands>
+      <command>deploy --to h2 --dry --out "${project.basedir}/src/main/resources/schema-h2.sql"</command>
+    </commands>
+  </configuration>
+</execution>
+```
+:::
 
 You can also run the command manually to see the generated DDL for your models. For example, to inspect what the SQL DDL for your entire model would look like, simply run:
 
@@ -60,32 +77,9 @@ code --diff _out/c/sqlite.sql _out/c/h2.sql
 > [!tip] CDS models are database-agnostic
 > CDS models are designed to be database-agnostic, allowing you to switch between different databases with minimal changes. The `--dialect` option helps you see how your models translate to different database-specific DDLs. \
 
-
-### Dialects by `cds env` Profiles
-
-The dialect is automatically inferred from your project configuration and the current profile, so you typically don't need to specify it explicitly. For example, if your project is configured to use SAP HANA in production and SQLite in development, the respective dialects will be applied automatically.
-Try this out using the `--profile` option:
-
-```shell
-cds compile \* --to sql --profile development
-cds compile \* --to sql --profile production
-```
-
- ::: details Use `cds env` to check your effective configurations:
-```shell
-cds env requires.db --profile development
-cds env requires.db --profile production
-```
-:::
-
-> [!tip] Dialects are inferred from profiles automatically
-> You typically don't need to specify the `--dialect` option manually, as it is derived from your project configuration and the active profile.
-
-
-
 ### Using `cds deploy`
 
-We can use `cds deploy` to inspect the generated DDL without actually deploying it, by using the `--dry` option. This will print the ultimate DDL statements to the console instead of executing them against the database, for example:
+We can use `cds deploy` to inspect the generated DDL without actually deploying it, by using the `--dry` option. This will print the DDL statements to the console instead of executing them against the database, for example:
 
 ```shell
 cds deploy --dry
@@ -134,6 +128,24 @@ Essentially, `cds deploy`  calls  `cds compile --to sql` under the hood, but goe
 > [!note] Ad-hoc Deployments
 > Without the `--dry` option, `cds deploy` would not only compile your CDS models to DDL, but would also do an ad-hoc deployment to the target database, if available. How that works is explained in more detail in the database-specific guides for [_SAP HANA_](hana), [_SQLite_](sqlite), and [_PostgreSQL_](postgres).
 
+### Dialects by `cds env` Profiles for CAP Node.js
+
+The dialect is automatically inferred from your project configuration, and the current profile, so you typically don't need to specify it explicitly. For example, if your project is configured to use SAP HANA in production and SQLite in development, the respective dialects will be applied automatically. Try this out using the `--profile` option:
+
+```shell
+cds deploy --dry --profile development
+cds deploy --dry --profile production
+```
+
+ ::: details Use `cds env` to check your effective configurations:
+```shell
+cds env requires.db --profile development
+cds env requires.db --profile production
+```
+:::
+
+> [!tip] Dialects are inferred from profiles automatically
+> You typically don't need to specify the `--dialect` option manually, as it is derived from your project configuration and the active profile.
 
 
 ## CDL ⇒ DDL Translation
@@ -181,13 +193,16 @@ CREATE TABLE sap_capire_bookshop_Books_Details ( ... );
 ```
 :::
 
-> [!tip] Guaranteed & Stable Slugification
-> The slugification effects are guaranteed and stable, which means that you can rely on it and use the slugified names in native SQL queries. For example, both of the following CQL queries are equivalent and will work as expected:
+> [!tip] You may use slugified names in CAP Node.js
+> In CAP Node.js, the slugification effects are guaranteed and stable, which means that you can rely on it and use the slugified names in _native SQL_ queries. For example, both of the following CQL queries are equivalent and will work as expected:
+>
+> ```js
+> await cds.run `SELECT from sap.capire.bookshop.Books`
+> await cds.run `SELECT from sap_capire_bookshop_Books`
+> ```
 
-```js
-await cds.run `SELECT from sap.capire.bookshop.Books`
-await cds.run `SELECT from sap_capire_bookshop_Books`
-```
+> [!warning] Don't use slugified names in CAP Java
+In CAP Java, you can use fully qualified entity names with dots. The slugified names can't be used in CQL queries.
 
 > [!tip]
 > Prefer entity names like `Books.Details` over _CamelCase_ variants like `BooksDetails`. While both work equally, they show up differently in native tools of databases that don't preserve case, for example in SAP HANA: The former will show up as `BOOKS_DETAILS`, while the latter shows up as `BOOKSDETAILS`, which is harder to read.
@@ -276,14 +291,23 @@ CREATE TABLE Books (
 ```
 :::
 
-> [!tip] Guaranteed & Stable Flattening
-> The flattening effects are guaranteed and stable, which means that you can rely on it and use the flattened elements in native SQL queries. For example, both of the following CQL queries are equivalent and would work as expected:
+The flattening effects for structured elements are guaranteed and stable. If a CDS model is compiled for usage with OData only the flattened elements are preserved in the CDS model.
 
-```js
-await cds.run `SELECT price.amount from Books`
-await cds.run `SELECT price_amount from Books`
-```
+> [!tip] Use flattening in runtime queries in CAP Node.js
+> The flattening effects can also be used at runtime with CAP Node.js. For example, both of the following CQL queries are equivalent and would work as expected:
+>
+> ```js
+> await cds.run `SELECT price.amount from Books`
+> await cds.run `SELECT price_amount from Books`
+> ```
 
+> [!warning] No flattening in runtime queries in CAP Java
+> CAP Java does not perform an automatic flattening of path expressions:
+>
+> ```java
+> Select.from("Books").columns("price_amount"); // valid
+> Select.from("Books").columns("price.amount"); // invalid
+> ```
 
 ### Associations ⇒ JOINs
 
@@ -467,13 +491,18 @@ However, even though CAP allows this, and handles all accesses correctly, it is
 > [!warning]  DON'T use Database-Invalid Names!
 > It's **strongly discouraged** to use names that contain non-ASCII characters, or conflict with database reserved words. Even more avoid [delimited names](../../cds/cdl#keywords-identifiers) in CDS models in the first place, as that impacts readability of your models.
 
+> [!warning]  Avoid using reserved Java keywords
+> CAP Java generates [accessor interfaces](../../java/cds-data#generated-accessor-interfaces) for CDS entities, using Java keywords as identifiers in a CDS model may result in generated interfaces that fail to compile. Use the `@cds.java.name` annotation to mitigate such conflicts, if you can't change the identifier names.
+
+
 ###### reserved-words
 > [!tip] Lists of Reserved Words
 > Check out the reserved words for the databases you are targeting: \
 > [_SAP HANA_](https://help.sap.com/docs/HANA_CLOUD_DATABASE/c1d3f60099654ecfb3fe36ac93c121bb/28bcd6af3eb6437892719f7c27a8a285.html)
 > , [_SQLite_](https://www.sqlite.org/lang_keywords.html)
 > , [_H2_](https://www.h2database.com/html/advanced.html#keywords)
 > , [_PostgreSQL_](https://www.postgresql.org/docs/current/sql-keywords-appendix.html)
+> , [_Java_](https://docs.oracle.com/javase/tutorial/java/nutsandbolts/_keywords.html)
 
 
 

guides/databases/h2.md

@@ -1,11 +1,37 @@
 
 # Using H2 for Development in CAP Java
 
+For local development and testing, CAP Java supports the [H2](https://www.h2database.com/) database, which can be configured to run in-memory, which allows projects to speed up development by magnitudes at minimized costs.
+
 > [!NOTE]
 > H2 is supported for CAP Java only.
 
-For local development and testing, CAP Java supports the [H2](https://www.h2database.com/) database, which can be configured to run in-memory.
+[[toc]]
+
+## Setup for H2
+
+### Using `cds add java`
+
+By default, a CAP Java project is configured to use H2 as an in-memory database with the `default` Spring profile, which is activated on local host and when tests are executed by the CI server.
+
+You can 
+
+
+
+### Using `cds add h2`
+
+If you Run this to set up H2 in your CAP project:
+
+```sh
+cds add sqlite
+```
+
+Essentially this is doing the following:
+
+- For CAP Node.js projects, it adds the `@cap-js/sqlite` package.
+- For CAP Java projects, it adds a Maven dependency for the SQLite JDBC driver.
+
 
-Learn more about the [features and limitations of using CAP with H2.](../../java/cqn-services/persistence-services#h2)
+Learn more about the [features and limitations of using CAP with H2.](../../java/cqn-services/persistence-services#h2) {.learn-more}
 
-There are various options of how to configure the [H2 database for local development and testing in CAP Java.](../../java/developing-applications/testing#setup-configuration)
+Learn more about the various options of how to configure the [H2 database for local development and testing in CAP Java.](../../java/developing-applications/testing#setup-configuration) {.learn-more}

guides/databases/index.md

@@ -1,10 +1,10 @@
 
 # CAP-Level Database Integration
 
-CAP application developers [focus on their domain](../../get-started/features#focus-on-domain), while CAP takes care of all aspects of database integration. This includes translating CDS models to native persistence models, schema evolution, deployment, as well as runtime querying – all of that in a database-agnostic way. [SQLite](./sqlite) <sup>1</sup> in-memory databases are automatically used in inner-loop development, while in production, [SAP HANA](./hana) <sup>2</sup> is used by default.
+CAP application developers [focus on their domain](../../get-started/features#focus-on-domain), while CAP takes care of all aspects of database integration. This includes translating CDS models to native persistence models, schema evolution, deployment, as well as runtime querying – all of that in a database-agnostic way. A lightweight in-memory database<sup>1</sup> is automatically used in inner-loop development, while in production, [SAP HANA](./hana) <sup>2</sup> is used by default.
 {.abstract}
 
-> _<sup>1</sup> or [H2](./h2) in case of CAP Java-based projects_.\
+> _<sup>1</sup> [SQLite](./sqlite) or [H2](./h2) (for CAP Java)_.\
 > _<sup>2</sup> or [PostgreSQL](./postgres) in edge cases_.