From b5b042ed30ed1bc9e6cfc013145171bb2d2ba39f Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Mon, 15 Jan 2024 17:57:54 +0100 Subject: [PATCH 1/8] Document limitations for Select ... lock() --- java/query-api.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/java/query-api.md b/java/query-api.md index f40eafe2b..098322989 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -758,6 +758,16 @@ import static com.sap.cds.ql.cqn.CqnLock.Mode.SHARED; Select.from("bookshop.Books").byId(1).lock(SHARED); ``` +Not every database entity exposed via the CDS entity can be locked with the `lock()` clause. Databases require that the target of such statements is represented by a single table or a view that is based on a single table without aggregation, joining or coalescence of values and the statement itself must not introduce aggregations, for example, by adding `groupBy()` clauses. Some databases might have additional restrictions or limitations specific to them. + +There are few notable examples of such restrictions: + +* You cannot use `lock()` and `distinct()` in the same statement. +* Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described here [Modifying Request Context](./request-contexts#modifying-requestcontext). +* Entities that contains "on-read" caclulated elements can't be locked when the statement contains statement that references them. Only non-calculated part of the entity can be used in the statement. + +As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. + ## Insert The [Insert](../cds/cqn#insert) statement inserts new data into a target entity set. From 2234b34ce0955dab597a6eaa592fb45574d1a3b2 Mon Sep 17 00:00:00 2001 From: Vladimir Date: Mon, 15 Jan 2024 18:02:59 +0100 Subject: [PATCH 2/8] Update java/query-api.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- java/query-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/query-api.md b/java/query-api.md index 098322989..a19cc1b3a 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -764,7 +764,7 @@ There are few notable examples of such restrictions: * You cannot use `lock()` and `distinct()` in the same statement. * Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described here [Modifying Request Context](./request-contexts#modifying-requestcontext). -* Entities that contains "on-read" caclulated elements can't be locked when the statement contains statement that references them. Only non-calculated part of the entity can be used in the statement. +* Entities that contains "on-read" calculated elements can't be locked when the statement contains statement that references them. Only non-calculated part of the entity can be used in the statement. As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. From 5d508dbcbb0fae3dce94e65f31930a498449145d Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Tue, 16 Jan 2024 14:06:06 +0100 Subject: [PATCH 3/8] improve wording about calculated elements --- java/query-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/query-api.md b/java/query-api.md index a19cc1b3a..9845c65f0 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -764,7 +764,7 @@ There are few notable examples of such restrictions: * You cannot use `lock()` and `distinct()` in the same statement. * Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described here [Modifying Request Context](./request-contexts#modifying-requestcontext). -* Entities that contains "on-read" calculated elements can't be locked when the statement contains statement that references them. Only non-calculated part of the entity can be used in the statement. +* Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or filter. As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. From 8f09f58d7aa671dc1749a6a789be8586de551905 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Tue, 16 Jan 2024 14:07:10 +0100 Subject: [PATCH 4/8] improve wording about localized entities --- java/query-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/query-api.md b/java/query-api.md index 9845c65f0..123572c21 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -763,7 +763,7 @@ Not every database entity exposed via the CDS entity can be locked with the `loc There are few notable examples of such restrictions: * You cannot use `lock()` and `distinct()` in the same statement. -* Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described here [Modifying Request Context](./request-contexts#modifying-requestcontext). +* Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). * Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or filter. As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. From c7486d7129a001fad20379bffd903d4d8818cd61 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Tue, 16 Jan 2024 14:09:17 +0100 Subject: [PATCH 5/8] improve wording about calculated elements --- java/query-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/query-api.md b/java/query-api.md index 123572c21..1df6d9eef 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -764,7 +764,7 @@ There are few notable examples of such restrictions: * You cannot use `lock()` and `distinct()` in the same statement. * Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). -* Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or filter. +* Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or a filter. As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. From 2a84e73fe64ba5eb8d830099c5fdcb607cf42b70 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Tue, 16 Jan 2024 17:02:51 +0100 Subject: [PATCH 6/8] Adopt feedback --- java/query-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/java/query-api.md b/java/query-api.md index 1df6d9eef..3a5ccb303 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -758,13 +758,13 @@ import static com.sap.cds.ql.cqn.CqnLock.Mode.SHARED; Select.from("bookshop.Books").byId(1).lock(SHARED); ``` -Not every database entity exposed via the CDS entity can be locked with the `lock()` clause. Databases require that the target of such statements is represented by a single table or a view that is based on a single table without aggregation, joining or coalescence of values and the statement itself must not introduce aggregations, for example, by adding `groupBy()` clauses. Some databases might have additional restrictions or limitations specific to them. +Not every entity exposed via the CDS entity can be locked with the `lock()` clause. Databases require that the target of such statements is represented by a single table or by a view that is simple enough so that the database can unambiguously identify which rows must be locked. Views that use joins, aggregate data, include calculated or coalesced fields cannot be locked. Some databases might have additional restrictions or limitations specific to them. -There are few notable examples of such restrictions: +There are few notable examples of such restrictions: -* You cannot use `lock()` and `distinct()` in the same statement. -* Localized entities can be locked only if you manually reset the locale via dedicated request context without the locale as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). -* Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or a filter. +* You cannot use `lock()` together with `distinct()` or `groupBy()`. +* Localized entities can be locked only if you query is executed without a locale as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). +* Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or a filter. As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. From 628afd77af2656ce42335c7ff008f5df07130255 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Wed, 17 Jan 2024 10:07:52 +0100 Subject: [PATCH 7/8] Mention subqueries --- java/query-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/java/query-api.md b/java/query-api.md index 3a5ccb303..347363d24 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -762,7 +762,8 @@ Not every entity exposed via the CDS entity can be locked with the `lock()` clau There are few notable examples of such restrictions: -* You cannot use `lock()` together with `distinct()` or `groupBy()`. +* You cannot use the `lock()` together with a `distinct()` or a `groupBy()`. +* You cannot use the `lock()` in a statement with the subquery as a source. * Localized entities can be locked only if you query is executed without a locale as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). * Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or a filter. From b1cd181213576d74472c3e4d81f2e723fc6d4b44 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 19 Jan 2024 08:55:18 +0100 Subject: [PATCH 8/8] editing --- java/query-api.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/java/query-api.md b/java/query-api.md index 347363d24..056b82fb7 100644 --- a/java/query-api.md +++ b/java/query-api.md @@ -750,7 +750,7 @@ Select.from("bookshop.Books").byId(1).lock(5); Update.entity("bookshop.Books").data("price", 18).byId(1); ``` -To set a _shared_ (read) lock specify the lock mode `SHARED` in the lock method: +To set a _shared_ (read) lock, specify the lock mode `SHARED` in the lock method: ```java import static com.sap.cds.ql.cqn.CqnLock.Mode.SHARED; @@ -758,16 +758,20 @@ import static com.sap.cds.ql.cqn.CqnLock.Mode.SHARED; Select.from("bookshop.Books").byId(1).lock(SHARED); ``` -Not every entity exposed via the CDS entity can be locked with the `lock()` clause. Databases require that the target of such statements is represented by a single table or by a view that is simple enough so that the database can unambiguously identify which rows must be locked. Views that use joins, aggregate data, include calculated or coalesced fields cannot be locked. Some databases might have additional restrictions or limitations specific to them. +Not every entity exposed via a CDS entity can be locked with the `lock()` clause. To use the `lock()` clause, databases require that the target of such statements is represented by one of the following: +- a single table +- a simple view, so that the database can unambiguously identify which rows to lock + +Views that use joins, aggregate data, include calculated or coalesced fields cannot be locked. Some databases might have additional restrictions or limitations specific to them. There are few notable examples of such restrictions: * You cannot use the `lock()` together with a `distinct()` or a `groupBy()`. * You cannot use the `lock()` in a statement with the subquery as a source. -* Localized entities can be locked only if you query is executed without a locale as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). -* Entities that contains "on-read" calculated elements can't be locked when the statement references them in the select list or a filter. +* Localized entities can be locked only if your query is executed without a locale, as described in the chapter [Modifying Request Context](./request-contexts#modifying-requestcontext). +* Entities that contain "on-read" calculated elements can't be locked when the statement references them in the select list or a filter. -As a general rule, prefer the statements that select primary keys with a simple conditions, such as `byId` or `matching`, to select the target entity set for locking. +As a general rule, prefer the statements that select primary keys with a simple condition, such as `byId` or `matching`, to select the target entity set that is locked. ## Insert