Fixed database guides

Author: danjoa

cds/cxl.md

@@ -340,7 +340,7 @@ that multiplies the two factors `price` and `quantity`.
 </div>
 
 
-CAP supports a set of [portable functions](../guides/databases/cql-to-sql.md#portable-functions) that can be used in all expressions. Those functions are passed through to the underlying database, allowing you to leverage the same functions for different databases, which greatly enhances portability.
+CAP supports a set of [portable functions](../guides/databases/cap-level-dbs#portable-functions) that can be used in all expressions. Those functions are passed through to the underlying database, allowing you to leverage the same functions for different databases, which greatly enhances portability.
 
 ## ref (path expression) { #ref }
 
@@ -835,4 +835,3 @@ navigates along the `author` association of the `Books` entity only if the autho
 }
 
 </style>
-

guides/databases/_menu.md

@@ -1,5 +1,5 @@
 <!-- # [ CAP-level Database Usage ](index.md) -->
-# [ Mocked Out of the Box ](cql-to-sql)
+# [ CAP-level Database Support ](cap-level-dbs)
 # [ CDL Compiled to DDL ](cdl-to-ddl)
 # [ Adding Initial Data ](initial-data.md)
 # Deployed to ...

guides/databases/cql-to-sql.md guides/databases/cap-level-dbs.mdguides/databases/cql-to-sql.md renamed to guides/databases/cap-level-dbs.md

@@ -1,12 +1,26 @@
-# CDS Compilation to Database-Specific SQL
+# CAP-Level Database Integration
 
 CAP supports a number of portable functions and operators in CQL. The compiler automatically translates these to the best-possible database-specific native SQL equivalents. You can safely use these in CDS view definitions and runtime queries expressed in CQL.
 {.abstract}
 
 [[toc]]
 
 
-## Operators
+## Mocked Out of the Box
+
+When using CAP's mocked out-of-the-box database integration, these functions and operators are supported in the in-memory SQLite database used for development and testing.
+
+#### TODO: 
+
+- Mocked by in-memory SQLite or H2 databases
+- With SAP HANA or PostgreSQL for production
+- With a defined set of portable functions and operators
+
+## Standard Operators
+
+This chapter lists standardized operators supported by CAP, and guaranteed to work across all supported databases with feature parity. You can safely use these in CDS view definitions and runtime queries expressed in CQL. The compiler translates them to the best-possible database-specific native SQL equivalents.
+
+### Standard SQL Operators
 
 Most native SQL operators are supported in CQL as-is, like these from the SQL92 standard:
 
@@ -77,13 +91,15 @@ FROM Books;
 The compiler translates this operator to the best-possible equivalent in the target database: `CASE WHEN ... THEN ... ELSE ... END` in standard SQL, or `IF(..., ..., ...)` in SAP HANA.
 
 
-## Functions
+## Standard Functions
 
-### Portable Functions
+The following sections list standardized string, numeric, data/time, and aggregate functions supported by CAP, and guaranteed to work across all supported databases with feature parity. You can safely use these in CDS view definitions and runtime queries expressed in CQL. The compiler translates them to the best-possible database-specific native SQL equivalents.
+
+> [!important] Function names are case-sensitive
+> The names for standardized functions must be written exactly as listed above. 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.
 
-Following are portable functions supported by CAP. You can safely use these in CDS view definitions and runtime queries expressed in CQL. The compiler translates them to the best-possible database-specific native SQL equivalents.
 
-String functions:
+### String Functions
 
 - `concat(x,y,...)`
 - `length(x)`
@@ -97,48 +113,63 @@ String functions:
 - `substring(x,start, length)`
 - `matchespattern(x,pattern)`
 
+In addition, to `concat()`, CAP also supports the common `||` operator for string concatenation in CQL queries, same as in SQL queries. For example, these two queries are equivalent:
+
+```sql
+SELECT concat (firstName,' ',lastName) as fullName from Authors;
+```
+```sql
+SELECT firstName || ' ' || lastName as fullName from Authors;
+``` 
+
+
+> [!important] Indexes and Substring Details
+> The return value of `indexof()` as well as the `start` parameter in `substring()` are zero-based index values. If the substring is not found, `indexof()` returns `-1`. If the `start` index in `substring()` is negative, it is counted from the end of the string. If the `length` parameter is omitted, the substring to the end of the string is returned.
 
-Numeric functions:
+
+### Numeric Functions
 
 - `ceil(x)`, `ceiling(x)`
 - `floor(x)`
 - `round(x)`
 
-###### aggregate-functions
-Aggregate functions:
+> [!warning] Non-portable <code>round()</code> function with more than one argument
+> Note that databases support `round()` functions with multiple arguments, the second parameter being the precision. If you use that option, the `round()` function may behave differently depending on the database.
+
+
+### Date / Time Functions
+
+- `date(x)` -> `yyyy-MM-dd` strings
+- `time(x)` -> `HH:mm:ss` strings
+   <br/><br/>
+- `year(x)` -> integer
+- `month(x)` -> integer
+- `day(x)` -> integer
+- `hour(x)` -> integer
+- `minute(x)` -> integer
+- `second(x)` -> integer
+   <br/><br/>
+- `years_between(x,y)` -> number
+- `months_between(x,y)` -> number
+- `days_between(x,y)` -> number
+- `seconds_between(x,y)` -> number
+
+> [!note] CAP Java support coming soon...
+> The above `*_between` functions are currently only supported by CAP Node.js. \
+> Support for CAP Java is planned for a future release.
+
+
+### Aggregate Functions
 
 - `avg(x)`, `average(x)`
 - `min(x)`, `max(x)`
 - `sum(x)`
 - `count(x)`
 <!-- - `countdistinct(x)` -->
 
-Date / Time functions:
-
-- `date(x)` -> `yyyy-MM-dd`
-- `time(x)` -> `HH:mm:ss`
-- `year(x)`
-- `month(x)`
-- `day(x)`
-- `hour(x)`
-- `minute(x)`
-- `second(x)`
-- `years_between(x,y)`
-- `months_between(x,y)`
-- `days_between(x,y)`
-- `seconds_between(x,y)`
-
-> [!important] Function names are case-sensitive
-> The function names must be written exactly as listed above. 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.
-
-> [!important] Non-portable <code>round()</code> function with more than one argument
-> Note that databases support `round()` functions with multiple arguments, the second parameter being the precision. If you use that option, the `round()` function may behave differently depending on the database.
-
-> [!note] Indexes and Substring Details
-> The return value of `indexof()` as well as the `start` parameter in `substring()` are zero-based index values. If the substring is not found, `indexof()` returns `-1`. If the `start` index in `substring()` is negative, it is counted from the end of the string. If the `length` parameter is omitted, the substring to the end of the string is returned.
 
 
-### Native Functions
+## Native Functions
 
 In general, the CDS compiler doesn't 'understand' SQL functions but translates them to SQL _generically_ as long as they follow the standard call syntax of `fn(x,y,...)`. This allows to use all native database functions inside your CDS models, like this:
 
@@ -152,7 +183,7 @@ SELECT from Books {
 > Using native functions like this makes your CDS models database-specific, and thus less portable. Therefore, prefer using the [portable functions](#portable-functions) listed above whenever possible.
 
 
-### Window Functions
+## Window Functions
 
 [SQL window functions](https://en.wikipedia.org/wiki/Window_function_(SQL)) with `OVER` clauses are supported as well, for example:
 

guides/databases/cdl-to-ddl.md

@@ -160,7 +160,7 @@ CREATE VIEW SomeProjection AS SELECT ... FROM SomeEntity;
 :::
 
 > [!tip] Views are defined using CQL
-> Both view defined per `as projection on` and those using `as select from` are defined using CQL, which supports a broad scope of database-agnostic features. Learn more about that in the following guide: [_CQL Compilation to SQL_](cql-to-sql).
+> Both view defined per `as projection on` and those using `as select from` are defined using CQL, which supports a broad scope of database-agnostic features. Learn more about that in the following guide: [_CQL Compilation to SQL_](cap-level-dbs).
 
 #### Qualified Names ⇒ Slugified
 

guides/databases/index.md

@@ -37,19 +37,19 @@ The illustration below shows what happens automatically under the hood:
 
 The following guides explain the details of CAP-level database integration, which are mostly database-agnostic, and apply to all supported databases:
 
-[CDL Compiled to DDL](cdl-to-ddl.md) 
+[ CAP-level Database Integration ](cap-level-dbs.md) 
 : How database-agnostic CDS models in CDL format are compiled to native DDL statements for different databases.
 
-[CQL Compiled to SQL](cql-to-sql.md) 
+[ CQL Compiled to SQL ](cdl-to-ddl.md) 
 : How database-agnostic CDS queries in CQL format are compiled to native SQL statements for different databases.
 
-[Adding Initial Data](initial-data.md) 
+[ Adding Initial Data ](initial-data.md) 
 : How to provide initial data and test data using CSV files, which are loaded into the database automatically.
 
-[Schema Evolution](schema-evolution.md) 
+[ Schema Evolution ](schema-evolution.md) 
 : How to manage schema changes with appropriate schema evolution strategies for development and production.
 
-[Performance Guide](performance.md) 
+[ Performance Guide ](performance.md) 
 : Pointing out performance considerations, and common pitfalls.
 
 

java/working-with-cql/query-api.md

@@ -713,7 +713,7 @@ You can aggregate data in two ways:
 
 #### Aggregation Functions { #aggregation-functions }
 
-Use [aggregation functions](../../guides/databases/cql-to-sql#aggregate-functions) to calculate minimums, maximums, totals, averages, and counts of values. You can use them in *columns* of `Select` statements to include the aggregated values in the result set, or in the [having](#having) clause to filter based on aggregated values.
+Use [aggregation functions](../../guides/databases/cap-level-dbs#aggregate-functions) to calculate minimums, maximums, totals, averages, and counts of values. You can use them in *columns* of `Select` statements to include the aggregated values in the result set, or in the [having](#having) clause to filter based on aggregated values.
 
 
 #### Grouping { #grouping }