Different structure

Author: vmikhailenko

java/working-with-cql/query-api.md

@@ -1308,30 +1308,73 @@ The Query Builder API supports using expressions in many places. Expressions con
 
 ### Entity References {#entity-refs}
 
-Entity references specify entity sets. They can be used to define the target entity set of a [CQL](../../cds/cql) statement or be an argument of event handler. 
+Entity references specify entity sets and define the target entity set of a [CQL](../../cds/cql) statement or be an argument of event handler. 
 
-You can also get [entity references](query-execution#entity-refs) from the result of a CDS QL statement to address an entity via its key values in other statements.
+Reference consists of _segments_ that define the path from the entity's root to the certain part of it. Each segment has the _identifier_ with the name of the entity or an element and an optional filter _predicate_. These predicates might include other references.
 
-Each reference has ordered sequence of _segments_ that define the path from the entity's root to the certain part of it. Segment has the _identifier_ with the name of the entity or an element and optional filter _predicate_.
+References can be represented in the JSON following an [Expression](../../cds/cxn) notation. 
 
-Existing reference can be reused as an object or a variable, or a new reference can be built on top of it. References are not bound to the particular model and are not checked against it while they are being built.
+References are either _absolute_ or _relative_. Absolute refs always have fully qualified name of the type in their first segment. Relative references need other absolute reference to which they relate.
 
-References can be _absolute_ or _relative_. Absolute reference has fully qualified entity name as the identifier in the first segment. They usually have associations as their segments.
-
-You start with the reference pointing to a book with certain key. You build it using corresponding [model interfaces](../cqn-services/persistence-services#model-interfaces) providing you the methods that corresponds to the elements of the book.
+Simplest kind of absolute reference is the reference to the entity set, for example, to all books. 
 
 ```java
-StructuredType<?> bookWithId = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")); // Books(ID=...)
+Books_ books = CQL.entity(Books_.class); // {"ref":["sap.capire.bookshop.Books"]}
 
-// ref is complete and cannot be extended anymore
 StructuredTypeRef ref = bookWithId.asRef(); // or CqnStructuredTypeRef which is cleaner equivalent type
 ```
 
-This reference is absolute and can be used as the source of the statement or several statements.
+Method `asRef()` seals the reference and makes it immutable.
+
+Relative references typically reference elements of the entity, for example, title of the book. They are members of select list of the CQL statement and are relative to its source.
 
 ```java
-import com.sap.cds.ql.CQL;
+CqnElementRef title = CQL.entity(Books_.class).title(); // {"ref":["title"]}
+CqnElementRef dynamicTitle = CQL.get(Books.TITLE);      // {"ref":["title"]}
+```
+
+New references are constructed with [model interfaces](../cqn-services/persistence-services#model-interfaces) or via API that is also used to build [CQL statements](/java/working-with-cql/query-api#concepts). For most of the application code, the model interfaces are the recommended way to do this.
+
+References might also represent navigation within the structured entity or between different entities via its associations. For example, below is the reference that represents the path from the book to its chapters. 
+
+```java
+CqnStructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).chapters(c -> c.ID().eq("...")).pages(p -> p.ID().eq("...")).asRef();
+```
+
+Each segment of this reference has an identifier (typically an association or composition) and the filter.
+
+```json
+{
+  "ref": [
+    {
+      "id": "sap.capire.bookshop.Books",
+      "where": [
+        { "ref": ["ID"]}, "=", {"val": "..."}
+      ]
+    },
+    {
+      "id": "chapters",
+      "where": [
+        { "ref": ["ID"]}, "=", {"val": "..."}
+      ]
+    },
+    {
+      "id": "pages",
+      "where": [
+        { "ref": ["ID"]}, "=", {"val": "..."}
+      ]
+    }
+  ]
+}
+```
+
+Existing reference can be reused as an object or a variable, or a new reference can be built on top of it. They can be introspected with [`CqnVisitor`](/java/working-with-cql/query-introspection#cqnvisitor). They are not bound to the particular model and are not checked against it while they are being built. 
+
+Each reference can be serialized as JSON and also renders JSON as its `toString()` implementation. Do not use this JSON to process the references, for example, to extract values from them or to compare references between each other.
+
+Absolute references can be used as sources of the CQL statements and statements generated by CAP typically have them as their [sources](/java/working-with-cql/query-api#from-reference).
 
+```java
 // bookshop.Books[year = 2020].author // [!code focus]
 Authors_ authors = CQL.entity(Books_.class).filter(b -> b.year().eq(2020)).author(); // [!code focus]
 
@@ -1343,67 +1386,76 @@ StructuredType<?> authors =
 Select.from(authors).columns("name"); // [!code focus]
 ```
 
-If you want to use this ref to fetch the author of this book, you use `CQL.entity(...)` to make it typed again and add one more segment to it. Note, that this does not check that original ref is indeed the ref to the book, this only lets you use the required model interface.
+The resulting statement has two references: one absolute describing the author and the one relative, describing the name of the author.
+
+References can be analyzed with the [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer) to bind it back to the model, for example, to find annotations or extract filter values.
+
+The existing references obtained from the statements or [injected in custom handlers](/java/event-handlers/#entity-reference-arguments) can be used to produce new references. 
+
+Given that there is simple reference pointing to the book created as follows.
 
 ```java
-CqnStructuredTypeRef refToAuthor = CQL.entity(Books_.class, ref).author().asRef(); // Books(ID=...)/author
+// {"ref":[{"id":"sap.capire.bookshop.Books","where":[{"ref":["ID"]},"=",{"val":"..."}]}]}
+CqnStructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).asRef(); [!code focus]
 ```
 
-`CQL.to(...)` lets you use dynamic syntax to express the same.
+To navigate to author of the book, use `CQL.entity(...)` to make it typed again and add one more segment to it. Note, that this does not check that original reference is indeed the reference to the book, this only lets you use required model interface.
 
 ```java
-CqnStructuredTypeRef toAuthor = CQL.to(ref.segments()).to("author").asRef(); // Books(ID=...)/author
+// {"ref":[{"id":"sap.capire.bookshop.Books","where":[{"ref":["ID"]},"=",{"val":"..."}]},"author"]}
+CqnStructuredTypeRef refToAuthor = CQL.entity(Books_.class, ref).author().asRef(); // [!code focus]
 ```
 
-The result of both is the same reference. Model interfaces are strongly recommended for custom handlers as they are easier to use.
+With `CQL.to(...)` the same is produced dynamically.
 
-If you need to navigate to the parent, you can do it using the dynamic syntax to strip the last segment of it. This also accounts for the case when the reference contains longer path.
+```java
+// {"ref":[{"id":"sap.capire.bookshop.Books","where":[{"ref":["ID"]},"=",{"val":"..."}]},"author"]}
+CqnStructuredTypeRef toAuthor = CQL.to(ref.segments()).to("author").asRef(); // [!code focus]
+```
+
+This new reference might be used as the root of its own statement to read or change the author.
+
+With this one, one might need to navigate to the parent again. This is done by stripping the segments from the back of the reference.
 
 ```java
+// {"ref":[{"id":"sap.capire.bookshop.Books","where":[{"ref":["ID"]},"=",{"val":"..."}]}]}
 CqnStructuredTypeRef toParent = CQL.to(
-    refToAuthor.segments().subList(0, refToAuthor.segments().size() - 1)).asRef(); // Books(ID=...)
+    refToAuthor.segments().subList(0, refToAuthor.segments().size() - 1)).asRef(); // [!code focus]
 ```
 
-You can also construct ref that starts from the first segment to navigate to different path of the same root.
+There is the method `rootSegment()` that can be used to construct the reference starting with the same root as the existing reference. This is useful when you require navigation to different part of the same structured type, e.g. for example from the book's author to the pages of it.
 
 ```java
 CqnStructuredTypeRef toPagesOfTheBook = CQL.to(List.of(refToAuthor.rootSegment())).to("chapters").to("pages").asRef();
 ```
 
-You can use the `CQL.entity(...)` to use convenience of model interfaces by casing it.
+You can use the `CQL.entity(...)` to use convenience of model interfaces for this with additional cast.
 
 ```java
 CqnStructuredTypeRef toPagesOfTheBook = CQL.entity(Books_.class,
     CQL.to(List.of(refToAuthor.rootSegment())).asRef()).chapters().pages().asRef();
 ```
 
-Result of both statements above is the same reference and the values resulting from these are equivalent.
+Same references is produced as the result of last two statements. You, of course, have to provide the filters, if to-many associations used in them.
 
-To-many compositions usually require filters to be complete and you can use both static and dynamic API to include them as follows:
+References can be copied to produce other refs with in-place modification available for its segments as follows.
 
 ```java
-// yields Books(ID=...)/chapters(ID=...)/pages(ID=...)
-
-CqnStructuredTypeRef dynamicRef = CQL.to(List.of(refToAuthor.rootSegment())).to("chapters").filter(CQL.get("ID").eq("...")).asRef();
+StructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).chapters(c -> c.ID().eq("...")).pages(p -> p.ID().eq("...")).asRef();
+RefBuilder<StructuredTypeRef> builder = CQL.copy(ref);
+builder.segments().forEach(s -> {
+  // add new predicate to each segment
+  s.filter(CQL.and(CQL.get(Books.GENRE).eq("Fiction"), s.filter().orElse(null)));
+});
 
-CqnStructuredTypeRef staticRef = CQL.entity(Books_.class, 
-    CQL.to(List.of(refToAuthor.rootSegment())).asRef()).chapters(c -> c.ID().eq("...")).asRef();
+StructuredTypeRef copy = builder.build(); // new reference is ready
 ```
 
-Filters that you define for references can contain complex predicates referring to other elements, for example, to express complex conditions and path expressions.
-
-Segments of the references also usable as the variables and you can inspect them.
-
-```java
-r.rootSegment().id(); // yields Books
-r.rootSegment().filter(); // filter an Optional with the predicate
-```
+The code that manipulates the references must be tested thoroughly and you always need to ensure that you do not loose the filters or change the reference so that it becomes inconsistent.
 
-If you want to reflect the types behind the ref, you need to use [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer) that parses it and binds it back to the model. Use it, for example, to find annotations or extract key values.
-
-References are not comparable so they cannot be used as a keys in maps and values in the sets. You should not compare references between each other.
-
-Each reference can be serialized as JSON and also renders JSON as its `toString()` implementation. Do not use this JSON to process the references, for example, to extract values from them or to compare references between each other.
+:::warning Limitation
+The references are not comparable between each other. They cannot be used as keys of maps or values in a set.
+:::
 
 ### Elements References {#element-refs}