Merge branch 'main' into d032842_service_pojos

java/persistence-services.md

@@ -121,10 +121,25 @@ cds:
 
 ### SAP HANA
 
+#### Service Bindings
+
 SAP HANA can be configured when running locally as well as when running productively in the cloud. The datasource is auto-configured based on available service bindings in the `VCAP_SERVICES` environment variable or locally the _default-env.json_. This only works if an application profile is used, that doesn't explicitly configure a datasource using `spring.datasource.url`. Such an explicit configuration always takes precedence over service bindings from the environment.
 
 Service bindings of type *service-manager* and, in a Spring-based application, *hana* are used to auto-configure datasources. If multiple datasources are used by the application, you can select one auto-configured datasource to be used by the default Persistence Service through the property `cds.dataSource.binding`.
 
+#### SQL Optimization Mode
+
+By default, the SAP HANA adapter in CAP Java generates SQL that is compatible with SAP HANA 2.x ([HANA Service](https://help.sap.com/docs/HANA_SERVICE_CF/6a504812672d48ba865f4f4b268a881e/08c6e596b53843ad97ae68c2d2c237bc.html)) and [SAP HANA Cloud](https://www.sap.com/products/technology-platform/hana.html).
+To generate SQL that is optimized for the new [HEX engine](https://help.sap.com/docs/SAP_HANA_PLATFORM/9de0171a6027400bb3b9bee385222eff/3861d0908ef14e8bbec1d76ea871ac0f.html#sap-hana-execution-engine-(hex)) in SAP HANA Cloud, set the [CDS property](development/properties#cds-properties):
+
+```yaml
+cds.sql.hana.optimizationMode: hex
+```
+
+:::tip
+Use the [hints](../java/query-execution#hana-hints) `hdb.USE_HEX_PLAN` and `hdb.NO_USE_HEX_PLAN` to overrule the configured optimization mode per statement.
+:::
+
 ### PostgreSQL { #postgresql-1 }
 
 PostgreSQL can be configured when running locally as well as when running productively in the cloud. Similar to HANA, the datasource is auto-configured based on available service bindings, if the feature `cds-feature-postgresql` is added.

java/query-execution.md

@@ -275,6 +275,45 @@ entity DeliveredOrders as select from bookshop.Order where status = 'delivered';
 entity Orders as SELECT from bookshop.Order inner join bookshop.OrderHeader on Order.header.ID = OrderHeader.ID { Order.ID, Order.items, OrderHeader.status };
 ```
 
+## Runtime Views { #runtimeviews}
+
+The CDS compiler generates [SQL DDL](../guides/databases?impl-variant=java#generating-sql-ddl) statements based on your CDS model, which include SQL views for all CDS [views and projections](../cds/cdl#views-and-projections). This means adding or changing CDS views requires a deployment of the database schema changes.
+
+To avoid schema updates due to adding or updating CDS views, annotate them with [@cds.persistence.skip](../guides/databases#cds-persistence-skip). In this case the CDS compiler won't generate corresponding static database views. Instead, the CDS views are dynamically resolved by the CAP Java runtime.
+
+```cds
+entity Books {
+  key id     : UUID;
+      title  : String;
+      stock  : Integer;
+      author : Association to one Authors;
+}
+@cds.persistence.skip // [!code focus]
+entity BooksWithLowStock as projection on Books { // [!code focus]
+    id, title, author.name as author // [!code focus]
+} where stock < 10; // [!code focus]
+```
+
+At runtime, CAP Java resolves queries against runtime views until an entity is reached that isn't annotated with *@cds.persistence.skip*. For example, the CQL query
+
+```sql
+Select BooksWithLowStock where author = 'Kafka'
+```
+
+is executed against SQL databases as
+
+```SQL
+SELECT B.ID, B.TITLE, A.NAME as "author" FROM BOOKS B
+  LEFT OUTER JOIN AUTHORS A ON B.AUTHOR_ID = A.ID
+WHERE B.STOCK < 10 AND A.NAME = ?
+```
+
+::: tip
+Runtime views are supported for [CDS projections](../cds/cdl#as-projection-on). Constant values and expressions such as *case when* are currently ignored.
+
+Complex views using aggregations or union/join/subqueries in `FROM` are not yet supported.
+:::
+
 ### Using I/O Streams in Queries
 
 As described in section [Predefined Types](./data#predefined-types) it's possible to stream the data, if the element is annotated with `@Core.MediaType`. The following example demonstrates how to allocate the stream for element `coverImage`, pass it through the API to an underlying database and close the stream.