Document limitations for Select ... lock()

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 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:
+
+* 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.
+
 ## Insert
 
 The [Insert](../cds/cqn#insert) statement inserts new data into a target entity set.