From 516a609a585f513c4a225b044ac2f933a63e69ce Mon Sep 17 00:00:00 2001 From: I543501 <56645452+larsplessing@users.noreply.github.com> Date: Wed, 3 Dec 2025 16:10:28 +0100 Subject: [PATCH 1/7] runtime views for java and node --- cds/cdl.md | 80 ++++++++++++++++++++++++ java/migration.md | 2 +- java/working-with-cql/query-execution.md | 79 +---------------------- 3 files changed, 82 insertions(+), 79 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index 39fb01b314..8dba9a8565 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -856,7 +856,87 @@ 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](../../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 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](#hana-hints): + +```Java +Select.from(BooksWithLowStock).hint("cds.sql.runtimeView.mode", "resolve"); +``` +::: + +Node.js only provides the [cte](#rtview-cte) mode by default. Has to be 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 = ? +``` + +::: info Limitations of `cte` mode in Node.js +UNION, JOIN and localized fields are currently not supported. +::: + +::: 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](../../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. +::: ## Associations diff --git a/java/migration.md b/java/migration.md index 1697c152b1..9142a930f0 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 3b6b3c652c..9969e6210c 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. From 0f5612a942e360425b7ffd53cdca60718a14c375 Mon Sep 17 00:00:00 2001 From: D051920 Date: Thu, 4 Dec 2025 14:48:33 +0100 Subject: [PATCH 2/7] fix links and small changes --- cds/cdl.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index 8dba9a8565..c74e6d83b6 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -858,9 +858,9 @@ Result result = service.run(Select.from("UsingView"), params); ### 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. +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. +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 @@ -873,7 +873,12 @@ Select.from(BooksWithLowStock).hint("cds.sql.runtimeView.mode", "resolve"); ``` ::: -Node.js only provides the [cte](#rtview-cte) mode by default. Has to be enabled with cds.features.runtime_views: true. +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: @@ -912,10 +917,6 @@ SELECT ID, TITLE, AUTHOR AS "author" WHERE A.NAME = ? ``` -::: info Limitations of `cte` mode in Node.js -UNION, JOIN and localized fields are currently not supported. -::: - ::: tip CAP Java 3.10 Enable *cte* mode with *cds.sql.runtimeView.mode: cte* ::: @@ -932,10 +933,10 @@ SELECT B.ID, B.TITLE, A.NAME AS "author" ``` ::: 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. +Using associations that are only [defined](#associations) 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. +On PostgreSQL, some [pessimistic locking](../java/working-with-cql/query-execution/#pessimistic-locking) queries on runtime views navigating associations require the *cte* mode. ::: ## Associations From e2c38ffc741edce58743baf8873e3b100f640801 Mon Sep 17 00:00:00 2001 From: D051920 Date: Thu, 4 Dec 2025 14:57:25 +0100 Subject: [PATCH 3/7] fix link --- cds/cdl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/cdl.md b/cds/cdl.md index c74e6d83b6..0f16d88e4c 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] From 50bb602b22e5319a6c8b437fc3409258a416b291 Mon Sep 17 00:00:00 2001 From: I543501 <56645452+larsplessing@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:18:07 +0100 Subject: [PATCH 4/7] dead links --- cds/cdl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index 0f16d88e4c..c8cff4324b 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -866,14 +866,14 @@ CAP Java provides two modes for resolving runtime views during read operations: ::: 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](#hana-hints): +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. +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 From 5475f0e2c32baf274f96b0c2b24699a08f52a5d1 Mon Sep 17 00:00:00 2001 From: I543501 <56645452+larsplessing@users.noreply.github.com> Date: Thu, 4 Dec 2025 15:25:27 +0100 Subject: [PATCH 5/7] fix dead links --- cds/cdl.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cds/cdl.md b/cds/cdl.md index c8cff4324b..d499e474bf 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -860,7 +860,7 @@ Result result = service.run(Select.from("UsingView"), params); 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. +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 @@ -933,10 +933,10 @@ SELECT B.ID, B.TITLE, A.NAME AS "author" ``` ::: info Limitations of `resolve` mode -Using associations that are only [defined](#associations) in the view, as well as complex draft queries are not supported in *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. +On PostgreSQL, some [pessimistic locking](../java/working-with-cql/query-execution#pessimistic-locking) queries on runtime views navigating associations require the *cte* mode. ::: ## Associations From f2d709019926731deb57074197d07d188a13b5d7 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Thu, 4 Dec 2025 15:41:33 +0100 Subject: [PATCH 6/7] fix links --- java/working-with-cql/query-execution.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/java/working-with-cql/query-execution.md b/java/working-with-cql/query-execution.md index 9969e6210c..bae7806446 100644 --- a/java/working-with-cql/query-execution.md +++ b/java/working-with-cql/query-execution.md @@ -336,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) From b8cc43760a7ead5acd5727a18ec4b7f3fc84d010 Mon Sep 17 00:00:00 2001 From: Lars Plessing <56645452+larsplessing@users.noreply.github.com> Date: Thu, 4 Dec 2025 16:18:55 +0100 Subject: [PATCH 7/7] Update cds/cdl.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: René Jeglinsky --- cds/cdl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/cdl.md b/cds/cdl.md index d499e474bf..71ebb24038 100644 --- a/cds/cdl.md +++ b/cds/cdl.md @@ -923,7 +923,7 @@ 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. +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"