diff --git a/cds/cdl.md b/cds/cdl.md index 39fb01b31..71ebb2403 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -840,7 +840,7 @@ as SELECT * from SomeView(foo: 17, bar: :bar); For Node.js, there's no programmatic API yet. You need to provide a [CQN snippet](/cds/cqn#select). -In CAP Java, run a select statement against the view with named [parameter values](/java/working-with-cql/query-execution#querying-views): +In CAP Java, run a select statement against the view with named [parameter values](../java/working-with-cql/query-execution#querying-views): ::: code-group ```js [Node] @@ -856,7 +856,88 @@ Result result = service.run(Select.from("UsingView"), params); [Learn more about how to expose views with parameters in **Services - Exposed Entities**.](#exposed-entities){ .learn-more} [Learn more about views with parameters for existing HANA artifacts in **Native SAP HANA Artifacts**.](../advanced/hana){ .learn-more} +### Runtime Views { #runtimeviews } +To add or update CDS views without redeploying the database schema, annotate them with [@cds.persistence.skip](../guides/databases#cds-persistence-skip). This advises the CDS compiler to skip generating database views for these CDS views. Instead, CAP Java resolves them *at runtime* on each request. + +Runtime views must be simple [projections](#as-projection-on), not using *aggregations*, *join*, *union* or *subqueries* in the *from* clause, but may have a *where* condition if they are only used to read. CAP Java also supports writing through runtime views. The restrictions for [write through views](../java/working-with-cql/query-execution#updatable-views) apply in the same way as for standard CDS views. If a runtime view cannot be resolved, a fallback to database views is not possible, and the statement fails with an error. + +CAP Java provides two modes for resolving runtime views during read operations: [cte](#rtview-cte) and [resolve](#rtview-resolve). +::: details Changing the runtime view mode for CAP Java +To globally set the runtime view mode, use the property `cds.sql.runtimeView.mode` with value `cte` (the default) or `resolve` in the *application.yml*. To set the mode for a specific runtime view, annotate it with `@cds.java.runtimeView.mode: cte|resolve`. + +To set the mode for a specific query, use a [hint](../java/working-with-cql/query-execution#hana-hints): + +```Java +Select.from(BooksWithLowStock).hint("cds.sql.runtimeView.mode", "resolve"); +``` +::: + +Node.js only provides the [cte](#rtview-cte) mode. + +::: details Changing the runtime view mode for CAP Node.js +The runtime view mode can be globally enabled with +cds.features.runtime_views: true. +::: + +The next two sections introduce both modes using the following CDS model and query: + +```cds +entity Books { + key ID : UUID; + title : String; + stock : Integer; + author : Association to one Authors; +} +@cds.persistence.skip +entity BooksWithLowStock as projection on Books { + ID, title, author.name as author +} where stock < 10; // makes the view read only +``` +```sql +SELECT from BooksWithLowStock where author = 'Kafka' +``` + + +#### Read in `cte` mode { #rtview-cte } + +This is the default mode in Node.js and CAP Java `4.x`. The runtime translates the [view definition](#runtimeviews) into a _Common Table Expression_ (CTE) and sends it with the query to the database. + +```sql +WITH BOOKSWITHLOWSTOCK_CTE AS ( + SELECT B.ID, + B.TITLE, + A.NAME AS "AUTHOR" + FROM BOOKS B + LEFT OUTER JOIN AUTHOR A ON B.AUTHOR_ID = A.ID + WHERE B.STOCK < 10 +) +SELECT ID, TITLE, AUTHOR AS "author" + FROM BOOKSWITHLOWSTOCK_CTE + WHERE A.NAME = ? +``` + +::: tip CAP Java 3.10 +Enable *cte* mode with *cds.sql.runtimeView.mode: cte* +::: + +#### Read in `resolve` mode { #rtview-resolve } + +This mode is **only available in CAP Java**. The Java runtime _resolves_ the [view definition](#runtimeviews) to the underlying persistence entities and executes the query directly against the corresponding tables. + +```sql +SELECT B.ID, B.TITLE, A.NAME AS "author" + FROM BOOKS AS B + LEFT OUTER JOIN AUTHORS AS A ON B.AUTHOR_ID = A.ID + WHERE B.STOCK < 10 AND A.NAME = ? +``` + +::: info Limitations of `resolve` mode +Using associations that are only [defined](cql#association-definitions) in the view, as well as complex draft queries are not supported in *resolve* mode. +::: +::: info Pessimistic locking on PostgreSQL +On PostgreSQL, some [pessimistic locking](../java/working-with-cql/query-execution#pessimistic-locking) queries on runtime views navigating associations require the *cte* mode. +::: ## Associations diff --git a/java/migration.md b/java/migration.md index 1697c152b..9142a930f 100644 --- a/java/migration.md +++ b/java/migration.md @@ -98,7 +98,7 @@ Some property defaults have been adjusted: | `cds.security.authorization.instanceBased.rejectSelectedUnauthorizedEntity.enabled` | false | true | Requests that violate instance-based authorization conditions now fail with 403, instead of 404. | | `cds.security.authorization.instanceBased.checkInputData.enabled` | false | true | [Authorization Checks On Input Data](./security#input-data-auth) are now enabled by default. | | `cds.errors.defaultTranslations.enabled` | false | true | [Translations for Validation Error Messages](./event-handlers/indicating-errors#ootb-translated-messages) are now enabled by default. | -| `cds.sql.runtimeView.mode` | resolve | cte | [Runtime views](./working-with-cql/query-execution#runtimeviews) are now by default translated into Common Table Expressions | +| `cds.sql.runtimeView.mode` | resolve | cte | [Runtime views](../cds/cdl#runtimeviews) are now by default translated into Common Table Expressions | ### Deprecated Properties diff --git a/java/working-with-cql/query-execution.md b/java/working-with-cql/query-execution.md index 3b6b3c652..bae780644 100644 --- a/java/working-with-cql/query-execution.md +++ b/java/working-with-cql/query-execution.md @@ -236,7 +236,7 @@ Use the `@readonly` annotation to indicate that a view or a view element is not To [write data](#updatable-views) or [delete](#delete-via-view) through views, only use simple [projections](../../cds/cdl#as-projection-on). The CAP Java runtime attempts to resolve the CDS views to their underlying persistence entities, rewriting the statement and data accordingly, which is not supported for complex views. -For simple [projections](../../cds/cdl#as-projection-on), the generation of SQL views can be avoided by using [runtime views](#runtimeviews). This allows you to change the view definition without redeploying the database schema and is the prerequisite for lightweight extensibility via predefined extension fields. +For simple [projections](../../cds/cdl#as-projection-on), the generation of SQL views can be avoided by using [runtime views](../../cds/cdl#runtimeviews). This allows you to change the view definition without redeploying the database schema and is the prerequisite for lightweight extensibility via predefined extension fields. ::: tip Prefer simple views Apply the *Interface Segregation Principle*: design multiple simple views, each for a specific use case ([Single-Purposed Services](../../guides/providing-services#single-purposed-services)), rather than one complex view for many scenarios. @@ -319,83 +319,6 @@ DELETE from OrderView where ID = 42 ``` The delete operation is resolved to the underlying `Order` entity with ID *42* and cascades over the `header` and `items` compositions. The `delivery` composition, which is only defined in the view, is ignored and does not cascade the delete operation to `Delivery`. -### Runtime Views { #runtimeviews } - -To add or update CDS views without redeploying the database schema, annotate them with [@cds.persistence.skip](../../guides/databases#cds-persistence-skip). This advises the CDS compiler to skip generating database views for these CDS views. Instead, CAP Java resolves them *at runtime* on each request. - -Runtime views must be simple [projections](../../cds/cdl#as-projection-on), not using *aggregations*, *join*, *union* or *subqueries* in the *from* clause, but may have a *where* condition if they are only used to read. On write, the restrictions for [write through views](#updatable-views) apply in the same way as for standard CDS views. However, if a runtime view cannot be resolved, a fallback to database views is not possible, and the statement fails with an error. - -CAP Java provides two modes for resolving runtime views during read operations: [cte](#rtview-cte) and [resolve](#rtview-resolve). - -::: details Changing the runtime view mode -To globally set the runtime view mode, use the property `cds.sql.runtimeView.mode` with value `cte` (the default) or `resolve` in the *application.yml*. To set the mode for a specific runtime view, annotate it with `@cds.java.runtimeView.mode: cte|resolve`. - -To set the mode for a specific query, use a [hint](#hana-hints): - -```Java -Select.from(BooksWithLowStock).hint("cds.sql.runtimeView.mode", "resolve"); -``` -::: - -The next two sections introduce both modes using the following CDS model and query: - -```cds -entity Books { - key ID : UUID; - title : String; - stock : Integer; - author : Association to one Authors; -} -@cds.persistence.skip -entity BooksWithLowStock as projection on Books { - ID, title, author.name as author -} where stock < 10; // makes the view read only -``` -```sql -SELECT from BooksWithLowStock where author = 'Kafka' -``` - - -#### Read in `cte` mode { #rtview-cte } - -This is the default mode since CAP Java `4.x`. The runtime translates the [view definition](#runtimeviews) into a _Common Table Expression_ (CTE) and sends it with the query to the database. - -```sql -WITH BOOKSWITHLOWSTOCK_CTE AS ( - SELECT B.ID, - B.TITLE, - A.NAME AS "AUTHOR" - FROM BOOKS B - LEFT OUTER JOIN AUTHOR A ON B.AUTHOR_ID = A.ID - WHERE B.STOCK < 10 -) -SELECT ID, TITLE, AUTHOR AS "author" - FROM BOOKSWITHLOWSTOCK_CTE - WHERE A.NAME = ? -``` - -::: tip CAP Java 3.10 -Enable *cte* mode with *cds.sql.runtimeView.mode: cte* -::: - -#### Read in `resolve` mode { #rtview-resolve } - -The runtime _resolves_ the [view definition](#runtimeviews) to the underlying persistence entities and executes the query directly against the corresponding tables. - -```sql -SELECT B.ID, B.TITLE, A.NAME AS "author" - FROM BOOKS AS B - LEFT OUTER JOIN AUTHORS AS A ON B.AUTHOR_ID = A.ID - WHERE B.STOCK < 10 AND A.NAME = ? -``` - -::: info Limitations of `resolve` mode -Using associations that are only [defined](../../cds/cql#association-definitions) in the view, as well as complex draft queries are not supported in *resolve* mode. -::: -::: info Pessimistic locking on PostgreSQL -On PostgreSQL, some [pessimistic locking](#pessimistic-locking) queries on runtime views navigating associations require the *cte* mode. -::: - ### Draft Queries on Views { #draft-views } When draft-enabling a CDS view, the CDS Compiler creates a corresponding draft persistence table for this view. [Draft activate](../fiori-drafts#editing-drafts) updates the active entity via the view. @@ -413,14 +336,14 @@ If you define runtime views on [draft-enabled](../fiori-drafts#reading-drafts) e ::: ::: warning Avoid draft-enabling runtime views -Draft-enabling runtime views is only supported in [*CTE*](#rtview-cte) mode and requires a schema deployment to update the draft table when the runtime view is changed. +Draft-enabling runtime views is only supported in [*CTE*](/cds/cdl#rtview-cte) mode and requires a schema deployment to update the draft table when the runtime view is changed. ::: ### Views on Remote Services When delegating queries between Application Services and Remote Services, statements are resolved to the targeted service's entity definition by the CAP Java runtime. -For read, the CDS views are resolved similar to the runtime view [resolve](#rtview-resolve) mode. For write operations, views targeting *remote OData* services must fulfill the following: +For read, the CDS views are resolved similar to the runtime view [resolve](/cds/cdl#rtview-resolve) mode. For write operations, views targeting *remote OData* services must fulfill the following: - all requirements of [writable views](#updatable-views) - not include [calculated elements](../../cds/cdl#calculated-elements)