[Java] Document references #2153

vmikhailenko · 2025-10-15T14:57:48Z

The application developers are now exposed to the concept of references via arguments of custom handlers.

They should now what these are and how you supposed to work with them.

We can also improve the APIs a bit as some of these look rather ugly.

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

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4467 | Completion Tokens: 2078}

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

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4495 | Completion Tokens: 2260}

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

renejeglinsky · 2025-11-05T11:04:49Z

Hi @vmikhailenko ,
I enabled an AI editing workflow and would like to collect your feedback on the current suggestions. Please go through the suggestions and apply the ones you deem helpful. Afterwards please send me a little feedback/summary of what you think it does good and what you didn't like. Thank you :)

github-actions

Here's a collaborative code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full creative control over your code—AI simply provides additional perspective to support your decision-making process. Use whatever feels valuable and aligns with your project goals.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4523 | Completion Tokens: 635}

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

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4261 | Completion Tokens: 587}

github-actions · 2025-11-06T09:59:05Z

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

+}
+```
+
+Below is an example how this can be used together to build an CQL statement:


Grammar error: Missing article 'a' before 'CQL statement'. The sentence should read: 'Below is an example of how this can be used together to build a CQL statement:'

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

github-actions · 2025-11-06T09:59:05Z

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

+The references are not comparable between each other. They cannot be used as map keys or set values.
+:::
+
+### Elements References {#element-refs}


Spelling error: 'Elements References' should be 'Element References' (singular form is more appropriate for a heading about the concept).

github-actions · 2025-11-06T09:59:05Z

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

+StructuredTypeRef copy = builder.build(); // new reference is ready
+```
+
+Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.


Clarity improvement: The phrase 'Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent' is vague and unclear. Consider revising to: 'Ensure thorough testing when modifying references to avoid omitting filters or creating inconsistent reference states.'

Suggested change

Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.

Ensure thorough testing when modifying references to avoid omitting filters or creating inconsistent reference states.

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

Co-authored-by: René Jeglinsky <rene.jeglinsky@sap.com>

github-actions

Here's a supportive code review enhanced with AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4261 | Completion Tokens: 582}

github-actions · 2025-11-06T11:31:15Z

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

+}
+```
+
+Below is an example how this can be used together to build an CQL statement:


Grammar error: Missing article 'a' before 'CQL statement'. The sentence should read: 'Below is an example of how this can be used together to build a CQL statement:'

github-actions · 2025-11-06T11:31:15Z

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

+
+Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.
+
+References can be analyzed using 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. References an be introspected with [`CqnVisitor`](/java/working-with-cql/query-introspection#cqnvisitor).


Spelling error: 'an be' should be 'can be'. The sentence should read: 'References can be introspected with CqnVisitor.'

github-actions · 2025-11-06T11:31:15Z

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

+The references are not comparable between each other. They cannot be used as map keys or set values.
+:::
+
+### Elements References {#element-refs}


Grammar error: The heading should be 'Element References' (not 'Elements References') to maintain consistency with the singular form used elsewhere in the document.

github-actions · 2025-11-06T11:31:15Z

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

+CqnStructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).asRef(); // [!code focus]
+```
+
+To navigate to the 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 the original reference is indeed the reference to the book. This only lets you use required model interface.


Clarity improvement: The sentence 'Note, that this does not check that the original reference is indeed the reference to the book' contains an unnecessary comma after 'Note' and could be clearer. Consider: 'Note that this does not verify that the original reference actually points to a book.'

github-actions · 2025-11-06T11:31:15Z

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

+
+This new reference might be used as the root of its own statement to read or change the author.
+
+To navigate to the parent, you can strip segment from the end of the ref.


Clarity improvement: The sentence 'To navigate to the parent, you can strip segment from the end of the ref' is missing an article. It should read: 'To navigate to the parent, you can strip a segment from the end of the ref.'

Co-authored-by: René Jeglinsky <rene.jeglinsky@sap.com>

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4261 | Completion Tokens: 623}

github-actions · 2025-11-06T11:35:22Z

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

-Entity references specify entity sets. They can be used to define the target entity set of a [CQL](../../cds/cql) statement. They can either be defined inline using lambda expressions in the Query Builder (see [Target Entity Sets](#target-entity-sets)) or via the `CQL.entity` method, which is available in an _untyped_ version as well as in a _typed_ version that uses the generated [model interfaces](../cqn-services/persistence-services#model-interfaces). The following example shows an entity reference describing the set of *authors* that have published books in the year 2020:
+Entity references specify entity sets and can define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.
+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The references are not bound to the particular model and are not checked against it while they are being built. 


Use active voice instead of passive voice. Change 'are not bound to the particular model and are not checked against it while they are being built' to 'The system does not bind references to a particular model and does not check them against it during construction.'

github-actions · 2025-11-06T11:35:22Z

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

+}
+```
+
+Below is an example how this can be used together to build an CQL statement:


Improve clarity and conciseness. The sentence 'Below is an example how this can be used together to build an CQL statement:' has grammatical issues. Change to 'The following example shows how to use this to build a CQL statement:'

github-actions · 2025-11-06T11:35:22Z

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

+
+This new reference might be used as the root of its own statement to read or change the author.
+
+To navigate to the parent, you can strip segment from the end of the ref.


Use active voice and improve clarity. Change 'To navigate to the parent, you can strip segment from the end of the ref' to 'To navigate to the parent, strip the segment from the end of the reference.' Also, 'segment' should be 'a segment' for proper grammar.

github-actions · 2025-11-06T11:35:23Z

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

+StructuredTypeRef copy = builder.build(); // new reference is ready
+```
+
+Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.


Improve clarity and fix grammar. Change 'Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent' to 'Test this code thoroughly to ensure you do not omit filters or make the reference inconsistent.'

github-actions · 2025-11-06T11:35:23Z

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

+
+### Elements References {#element-refs}
+
+An element reference points to an element of the entity. Such references are usually _relative_, they do not have the name of the entity in their root. They can include filters in their segments except _in the last one_.


Fix grammar and improve clarity. Change 'Such references are usually relative, they do not have the name of the entity in their root' to 'Such references are usually relative; they do not include the entity name in their root.' Use a semicolon to properly connect the related clauses.

… into java-document-refs

github-actions

Here's a supportive code review enhanced by AI assistance. These insights offer suggestions and observations that may help guide your development process. Please consider them as recommendations rather than definitive requirements. Your expertise and judgment remain the most important factors in making decisions about your code. The AI tools are simply here to provide additional perspective and support your work.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4255 | Completion Tokens: 640}

github-actions · 2025-11-06T11:37:18Z

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

+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The 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 references always have the fully qualified name of the type in their first segment.


Use active voice instead of passive voice. Change 'References are either absolute or relative' to 'References can be either absolute or relative' to make it more active and direct.

github-actions · 2025-11-06T11:37:18Z

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

+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 application code, the model interfaces are the recommended way to do this.


Improve clarity by restructuring this sentence. Consider: 'New references are constructed using model interfaces or via the API that builds CQL statements. For most application code, model interfaces are the recommended approach.'

github-actions · 2025-11-06T11:37:18Z

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

+}
+```
+
+Below is an example how this can be used together to build a CQL statement:


Fix grammatical error. Change 'Below is an example how this can be used together' to 'Below is an example of how this can be used together' - the preposition 'of' is needed after 'example'.

github-actions · 2025-11-06T11:37:19Z

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

+CqnStructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).asRef(); // [!code focus]
+```
+
+To navigate to the 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 the original reference is indeed the reference to the book. This only lets you use required model interface.


Improve sentence structure for better clarity. Change 'Note, that this does not check that the original reference is indeed the reference to the book. This only lets you use required model interface.' to 'Note that this does not verify that the original reference points to the book. This only allows you to use the required model interface.' Also remove the comma after 'Note'.

github-actions · 2025-11-06T11:37:19Z

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

+CqnElementRef nameOfAuthor = CQL.entity(Books_.class).filter(f -> f.ID().eq("...")).author().name();
+```

+They also share the same features and limitations as the entity references and they cannot be used with [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer).


Use active voice and improve clarity. Change 'They also share the same features and limitations as the entity references and they cannot be used with' to 'Element references share the same features and limitations as entity references and cannot be used with' to avoid repetition and make it more concise.

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4223 | Completion Tokens: 584}

github-actions · 2025-11-06T11:48:49Z

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

+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The 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 references always have the fully qualified name of the type in their first segment.


Use active voice instead of passive voice. Change "References are either absolute or relative" to "References can be either absolute or relative" to make the sentence more direct and engaging.

github-actions · 2025-11-06T11:48:49Z

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

+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 application code, the model interfaces are the recommended way to do this.


Improve clarity by restructuring this sentence. Consider: "For most application code, model interfaces are the recommended way to construct new references." This makes the recommendation clearer and more direct.

github-actions · 2025-11-06T11:48:50Z

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

+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.


Use active voice and improve clarity. Change "This new reference might be used as the root of its own statement" to "You can use this new reference as the root of its own statement" to be more direct and actionable.

github-actions · 2025-11-06T11:48:50Z

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

+
+This new reference might be used as the root of its own statement to read or change the author.
+
+To navigate to the parent, you can strip segment from the end of the ref.


Improve sentence structure for better readability. Change "To navigate to the parent, you can strip segment from the end of the ref" to "To navigate to the parent, you can strip a segment from the end of the reference." Note the addition of the article "a" and using "reference" instead of "ref" for consistency.

github-actions · 2025-11-06T11:48:50Z

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

+CqnElementRef nameOfAuthor = CQL.entity(Books_.class).filter(f -> f.ID().eq("...")).author().name();
+```

+Element references share the same features and limitations as entity references and cannot be used with [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer).


Use active voice and improve clarity. Change "Element references share the same features and limitations as entity references and cannot be used with" to "Element references have the same features and limitations as entity references and you cannot use them with" to make it more direct and clear.

github-actions

Here's a collaborative code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and context. The AI analysis is here to support your decision-making process and provide additional perspective on your code.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4223 | Completion Tokens: 515}

github-actions · 2025-11-06T11:49:19Z

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

+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The 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 references always have the fully qualified name of the type in their first segment.


Use active voice instead of passive voice. Change "References are either absolute or relative" to "References can be either absolute or relative" to make the sentence more direct and engaging.

github-actions · 2025-11-06T11:49:19Z

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

+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 application code, the model interfaces are the recommended way to do this.


Improve clarity by restructuring this sentence. Consider: "For most application code, model interfaces are the recommended way to construct new references." This makes the recommendation clearer and more direct.

github-actions · 2025-11-06T11:49:19Z

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

+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.


Use active voice and improve clarity. Change "This new reference might be used" to "You can use this new reference" to be more direct and actionable.

github-actions · 2025-11-06T11:49:20Z

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

+
+This new reference might be used as the root of its own statement to read or change the author.
+
+To navigate to the parent, you can strip segment from the end of the ref.


Grammar error: Add an article. Change "strip segment from the end" to "strip a segment from the end" for proper grammar.

github-actions · 2025-11-06T11:49:20Z

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

+StructuredTypeRef copy = builder.build(); // new reference is ready
+```
+
+Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.


Improve sentence structure and clarity. Consider: "Test this code thoroughly and ensure that you do not omit filters or make the reference inconsistent." This removes redundancy and improves flow.

github-actions

Here's a supportive code review enhanced by AI assistance. These insights offer suggestions and observations that may help guide your development process. Please consider them as recommendations rather than definitive requirements. Your expertise and judgment remain the most important factors in making decisions about your code. The AI analysis is simply here to provide additional perspective and support your work.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4216 | Completion Tokens: 672}

github-actions · 2025-11-06T11:55:15Z

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

+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The 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 references always have the fully qualified name of the type in their first segment.


Use active voice instead of passive voice. Change 'References are either absolute or relative' to 'References can be either absolute or relative' to make it more active and clear.

github-actions · 2025-11-06T11:55:15Z

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

+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 application code, the model interfaces are the recommended way to do this.


Improve clarity by restructuring this sentence. Consider: 'New references are constructed using model interfaces or via the API that builds CQL statements. For most application code, model interfaces are the recommended approach.'

github-actions · 2025-11-06T11:55:15Z

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

+CqnStructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).chapters(c -> c.ID().eq("...")).pages(p -> p.ID().eq("...")).asRef();
+```
+
+References can be represented as JSON following an [Expression](../../cds/cxn) notation. The following is the JSON representation of the reference above:


Use active voice and improve clarity. Change 'References can be represented as JSON following an Expression notation' to 'You can represent references as JSON using Expression notation.'

github-actions · 2025-11-06T11:55:15Z

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

+StructuredTypeRef copy = builder.build(); // new reference is ready
+```
+
+Test this code thoroughly and ensure that you do not omit filters or make the reference inconsistent.


Use active voice and present tense. Change 'Test this code thoroughly and ensure that you do not omit filters or make the reference inconsistent' to 'Test this code thoroughly and ensure that you do not omit filters or create inconsistent references.'

github-actions · 2025-11-06T11:55:15Z

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

+CqnElementRef nameOfAuthor = CQL.entity(Books_.class).filter(f -> f.ID().eq("...")).author().name();
+```

+Element references share the same features and limitations as entity references and cannot be used with [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer).


Use active voice and improve clarity. Change 'Element references share the same features and limitations as entity references and cannot be used with CqnAnalyzer' to 'Element references have the same features and limitations as entity references. You cannot use them with CqnAnalyzer.'

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's specific needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 4214 | Completion Tokens: 622}

github-actions · 2025-11-06T12:03:49Z

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

-Entity references specify entity sets. They can be used to define the target entity set of a [CQL](../../cds/cql) statement. They can either be defined inline using lambda expressions in the Query Builder (see [Target Entity Sets](#target-entity-sets)) or via the `CQL.entity` method, which is available in an _untyped_ version as well as in a _typed_ version that uses the generated [model interfaces](../cqn-services/persistence-services#model-interfaces). The following example shows an entity reference describing the set of *authors* that have published books in the year 2020:
+Entity references specify entity sets and can define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.
+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The references are not bound to the particular model and are not checked against it while they are being built.


Use active voice instead of passive voice. Change 'References are not bound to the particular model and are not checked against it while they are being built' to 'The system does not bind references to a particular model and does not check them against it during construction.'

github-actions · 2025-11-06T12:03:49Z

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

+CqnStructuredTypeRef ref = CQL.entity(Books_.class).filter(b -> b.ID().eq("...")).chapters(c -> c.ID().eq("...")).pages(p -> p.ID().eq("...")).asRef();
+```
+
+References have JSON representation that follows an [Expression](../../cds/cxn) notation. Below is the example if it:


Fix grammatical error. Change 'Below is the example if it:' to 'Below is an example of it:' - 'if' should be 'of'.

github-actions · 2025-11-06T12:03:49Z

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

+CqnStructuredTypeRef refToAuthor = CQL.entity(Books_.class, ref).author().asRef(); // [!code focus]
+```
+
+With `CQL.to(...)` the same is produced dynamically.


Use active voice and improve clarity. Change 'With CQL.to(...) the same is produced dynamically' to 'Use CQL.to(...) to produce the same result dynamically.'

github-actions · 2025-11-06T12:03:49Z

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

+An element reference points to an element of the entity. Such references are usually _relative_, they do not have the name of the entity in their root. They can include filters in their segments except _in the last one_.
+Most of the time, they exist as members of the [select list](#projections) of a statement or part of the statement, for example, of an expand predicate.


Use active voice instead of passive voice. Change 'Such references are usually relative, they do not have the name of the entity in their root. They can include filters in their segments except in the last one' to 'Such references are usually relative and do not have the entity name in their root. You can include filters in their segments except in the last one.'

github-actions · 2025-11-06T12:03:49Z

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

+CqnElementRef nameOfAuthor = CQL.entity(Books_.class).filter(f -> f.ID().eq("...")).author().name();
+```

+Element references share the same features and limitations as entity references and cannot be used with [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer).


Use active voice instead of passive voice. Change 'Element references share the same features and limitations as entity references and cannot be used with [CqnAnalyzer]' to 'Element references share the same features and limitations as entity references, and you cannot use them with [CqnAnalyzer]'.

github-actions

Here's a supportive code review enhanced by AI assistance. These insights offer suggestions and observations that may help guide your development process. Please consider them as recommendations rather than definitive requirements. Your expertise and judgment remain the most important factors in making decisions about your code. The AI analysis is simply here to provide additional perspective and support your work.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 3683 | Completion Tokens: 806}

github-actions · 2025-11-06T12:27:30Z

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

 ### 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. They can either be defined inline using lambda expressions in the Query Builder (see [Target Entity Sets](#target-entity-sets)) or via the `CQL.entity` method, which is available in an _untyped_ version as well as in a _typed_ version that uses the generated [model interfaces](../cqn-services/persistence-services#model-interfaces). The following example shows an entity reference describing the set of *authors* that have published books in the year 2020:
+Entity references specify entity sets and can define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.


Use active voice instead of passive voice. Change "They can be used" to "You can use them" for better clarity and directness.

Suggested revision:

Entity references specify entity sets and you can use them to define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.

github-actions · 2025-11-06T12:27:30Z

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

-Entity references specify entity sets. They can be used to define the target entity set of a [CQL](../../cds/cql) statement. They can either be defined inline using lambda expressions in the Query Builder (see [Target Entity Sets](#target-entity-sets)) or via the `CQL.entity` method, which is available in an _untyped_ version as well as in a _typed_ version that uses the generated [model interfaces](../cqn-services/persistence-services#model-interfaces). The following example shows an entity reference describing the set of *authors* that have published books in the year 2020:
+Entity references specify entity sets and can define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.
+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The references are not bound to the particular model and are not checked against it while they are being built.


Use present tense instead of future tense. The phrase "are not checked against it while they are being built" should be "are not checked against it during construction" to maintain present tense throughout.

Suggested revision:

The references are not bound to the particular model and are not checked against it during construction.

github-actions · 2025-11-06T12:27:30Z

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

+
+Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.
+
+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). Prefer model interfaces in the application code.


Use active voice and improve clarity. Change "New references are constructed" to "You construct new references" for better readability and active voice.

Suggested revision:

You construct new references 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). Prefer model interfaces in the application code.

github-actions · 2025-11-06T12:27:30Z

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

+
+### Element References {#element-refs}
+
+An element reference points to regular element of the entity. Such references are usually _relative_ and form select list for a CQL statement or an expand.


Improve clarity and fix grammatical error. "An element reference points to regular element" should be "An element reference points to a regular element" (missing article). Also, consider rephrasing for better flow.

Suggested revision:

An element reference points to a regular element of the entity. Such references are usually _relative_ and form the select list for a CQL statement or an expand.

github-actions · 2025-11-06T12:27:30Z

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

+CqnElementRef nameOfAuthor = CQL.entity(Books_.class).filter(f -> f.ID().eq("...")).author().name();
+```

+Element references share the same features and limitations as entity references and cannot be used with [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer).


Improve sentence structure and clarity. The sentence "Element references share the same features and limitations as entity references and cannot be used with [CqnAnalyzer]" could be clearer by separating the concepts.

Suggested revision:

Element references share the same features and limitations as entity references. However, you cannot use them with [`CqnAnalyzer`](/java/working-with-cql/query-introspection#cqnanalyzer).

github-actions

Here's a supportive code review enhanced by AI assistance. These suggestions offer potential improvements and insights to consider, though they're recommendations rather than requirements. You have full control over which feedback to implement based on your project's needs and goals. The AI analysis is here to complement your expertise and help streamline your development process.
_{Model: claude-sonnet-4-20250514 | Prompt Tokens: 3687 | Completion Tokens: 572}

github-actions · 2025-11-06T12:29:35Z

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

 ### 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. They can either be defined inline using lambda expressions in the Query Builder (see [Target Entity Sets](#target-entity-sets)) or via the `CQL.entity` method, which is available in an _untyped_ version as well as in a _typed_ version that uses the generated [model interfaces](../cqn-services/persistence-services#model-interfaces). The following example shows an entity reference describing the set of *authors* that have published books in the year 2020:
+Entity references specify entity sets and can define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.


The sentence structure is awkward and uses passive voice. Consider revising to:

"Entity references specify entity sets. You can use them to define the target entity set of a CQL statement or as arguments for event handlers."

github-actions · 2025-11-06T12:29:36Z

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

-Entity references specify entity sets. They can be used to define the target entity set of a [CQL](../../cds/cql) statement. They can either be defined inline using lambda expressions in the Query Builder (see [Target Entity Sets](#target-entity-sets)) or via the `CQL.entity` method, which is available in an _untyped_ version as well as in a _typed_ version that uses the generated [model interfaces](../cqn-services/persistence-services#model-interfaces). The following example shows an entity reference describing the set of *authors* that have published books in the year 2020:
+Entity references specify entity sets and can define the target entity set of a [CQL](../../cds/cql) statement or serve as an argument for event handlers.
+
+A reference consists of _segments_ that define the path from the entity's root to a 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. The references are not bound to the particular model and are not checked against it while they are being built.


This sentence uses passive voice and is unclear. Consider revising to:

"The system does not bind references to a particular model and does not check them against it while building them."

github-actions · 2025-11-06T12:29:36Z

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

+
+Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.
+
+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). Prefer model interfaces in the application code.


The sentence structure is unclear and uses passive voice. Consider revising to:

"You construct new references with model interfaces or via the API that you also use to build CQL statements. Use model interfaces in application code."

github-actions · 2025-11-06T12:29:36Z

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

+
+### Element References {#element-refs}
+
+An element reference points to a regular element of the entity. Such references are usually _relative_ and form select list for a CQL statement or an expand.


The sentence uses passive voice. Consider revising to:

"Such references are usually relative and form the select list for a CQL statement or an expand."

github-actions · 2025-11-06T12:29:36Z

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

+CqnElementRef extendedRef = CQL.to(relativeRef.segments()).get("name"); // author/placeOfBirth/name
+```
+
+You can create _absolute_ element references, but they are rarely used.


The sentence uses passive voice. Consider revising to:

"You rarely use absolute element references."

renejeglinsky

I guess it's ok to simplify the links like that. Or have you had a certain reason not to do it?

renejeglinsky · 2025-11-12T12:27:46Z

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

+
+The method `asRef()` seals the reference and makes it immutable.
+
+Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.


Suggested change

Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.

Relative references do not specify the type in the first segment and are [element references](#element-refs) most of the time.

renejeglinsky · 2025-11-12T12:28:08Z

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

+
+Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.
+
+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). Prefer model interfaces in the application code.


Suggested change

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). Prefer model interfaces in the application code.

New references are constructed with [model interfaces](../cqn-services/persistence-services#model-interfaces) or via API that is also used to build [CQL statements](#concepts). Prefer model interfaces in the application code.

renejeglinsky · 2025-11-12T12:32:54Z

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

+CqnElementRef relativeRef = statement.items().getFirst().asRef(); // author/placeOfBirth
+```
+
+Element references can be extended with the same APIs as the entity references.


Suggested change

Element references can be extended with the same APIs as the entity references.

Element references can be extended with the same APIs as the [entity references](#entity-refs).

renejeglinsky · 2025-11-12T12:36:19Z

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


-// bookshop.Books[year = 2020].author // [!code focus]
-Authors_ authors = CQL.entity(Books_.class).filter(b -> b.year().eq(2020)).author(); // [!code focus]
+Given a simple reference pointing to the book created as follows.


Suggested change

Given a simple reference pointing to the book created as follows.

For the upcoming examples, let's assume a simple reference pointing to the book created as follows:

vmikhailenko · 2025-11-12T12:50:04Z

Go ahead. I am also OK with textual changes.

agoerler · 2025-10-15T16:08:40Z

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

+
+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.
+
+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_.


Suggested change

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_.

Each reference has ordered sequence of _segments_ that defines 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_.

agoerler · 2025-10-15T16:09:06Z

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

+
+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_.
+
+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.


Suggested change

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.

An 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.

agoerler · 2025-10-15T16:09:41Z

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

+
+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 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.


Suggested change

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.

References can be _absolute_ or _relative_. An absolute reference has a fully qualified entity name as the identifier in the first segment. They usually have associations as their segments.

agoerler · 2025-10-15T16:09:57Z

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

+
+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.


Suggested change

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.

You start with the reference pointing to a book with a 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.

agoerler · 2025-10-15T16:11:15Z

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

+    refToAuthor.segments().subList(0, refToAuthor.segments().size() - 1)).asRef(); // Books(ID=...)
+```
+
+You can also construct ref that starts from the first segment to navigate to different path of the same root.


Suggested change

You can also construct ref that starts from the first segment to navigate to different path of the same root.

You can also construct a ref that starts from the first segment to navigate to different path of the same root.

Draft

e0c19c6

vmikhailenko requested a review from smahati as a code owner October 15, 2025 14:57

vmikhailenko requested review from MattSchur and agoerler October 15, 2025 14:57

vmikhailenko commented Oct 15, 2025

View reviewed changes

java/working-with-cql/query-api.md Outdated Show resolved Hide resolved

Different structure

3cfdad1

vmikhailenko commented Oct 16, 2025

View reviewed changes

java/working-with-cql/query-api.md Outdated Show resolved Hide resolved

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

36fbf31

renejeglinsky added the AI Review AI generated suggestions label Nov 5, 2025

Merge branch 'main' into java-document-refs

801631e

github-actions bot reviewed Nov 5, 2025

View reviewed changes

renejeglinsky added 2 commits November 5, 2025 10:41

Apply suggestions from code review

caa3892

Merge branch 'main' into java-document-refs

b1a24dd

github-actions bot reviewed Nov 5, 2025

View reviewed changes

Merge branch 'main' into java-document-refs

92a0ac3

github-actions bot reviewed Nov 6, 2025

View reviewed changes

rewrite

f295189

github-actions bot reviewed Nov 6, 2025

View reviewed changes

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

0f14609

Co-authored-by: René Jeglinsky <rene.jeglinsky@sap.com>

github-actions bot reviewed Nov 6, 2025

View reviewed changes

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

fb7591f

Co-authored-by: René Jeglinsky <rene.jeglinsky@sap.com>

github-actions bot reviewed Nov 6, 2025

View reviewed changes

vmikhailenko added 2 commits November 6, 2025 12:36

Apply suggestions

7a5c3c3

Merge remote-tracking branch 'refs/remotes/origin/java-document-refs'…

5d740ce

… into java-document-refs

github-actions bot reviewed Nov 6, 2025

View reviewed changes

vmikhailenko added 2 commits November 6, 2025 12:48

feedback

4a67d72

feedback

2e7d155

github-actions bot reviewed Nov 6, 2025

View reviewed changes

Feedback

51b74cd

github-actions bot reviewed Nov 6, 2025

View reviewed changes

feedback

91b2f00

github-actions bot reviewed Nov 6, 2025

View reviewed changes

Less text

5002237

github-actions bot reviewed Nov 6, 2025

View reviewed changes

feedback

1b1f731

github-actions bot reviewed Nov 6, 2025

View reviewed changes

renejeglinsky removed the AI Review AI generated suggestions label Nov 6, 2025

renejeglinsky added 4 commits November 6, 2025 14:36

Merge branch 'main' into java-document-refs

881693f

Merge branch 'main' into java-document-refs

278e74a

Merge branch 'main' into java-document-refs

46ecab7

Merge branch 'main' into java-document-refs

b47d480

renejeglinsky reviewed Nov 12, 2025

View reviewed changes

agoerler reviewed Nov 12, 2025

View reviewed changes

vmikhailenko added 2 commits November 12, 2025 16:33

Feedback

761a620

Small corrections

483e0a9

	Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.
	Ensure thorough testing when modifying references to avoid omitting filters or creating inconsistent reference states.


		Test this code thoroughly and ensure that you do not omit the filters or change the reference so that it becomes inconsistent.

		References can be analyzed using 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. References an be introspected with [`CqnVisitor`](/java/working-with-cql/query-introspection#cqnvisitor).


		This new reference might be used as the root of its own statement to read or change the author.

		To navigate to the parent, you can strip segment from the end of the ref.


		### Elements References {#element-refs}

		An element reference points to an element of the entity. Such references are usually _relative_, they do not have the name of the entity in their root. They can include filters in their segments except _in the last one_.


		A reference consists of _segments_ that define the path from the entity's root to a 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. The 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 references always have the fully qualified name of the type in their first segment.

		An element reference points to an element of the entity. Such references are usually _relative_, they do not have the name of the entity in their root. They can include filters in their segments except _in the last one_.
		Most of the time, they exist as members of the [select list](#projections) of a statement or part of the statement, for example, of an expand predicate.


		Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.

		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). Prefer model interfaces in the application code.


		### Element References {#element-refs}

		An element reference points to regular element of the entity. Such references are usually _relative_ and form select list for a CQL statement or an expand.


		### Element References {#element-refs}

		An element reference points to a regular element of the entity. Such references are usually _relative_ and form select list for a CQL statement or an expand.


		The method `asRef()` seals the reference and makes it immutable.

		Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.

	Element references can be extended with the same APIs as the entity references.
	Element references can be extended with the same APIs as the [entity references](#entity-refs).

	Given a simple reference pointing to the book created as follows.
	For the upcoming examples, let's assume a simple reference pointing to the book created as follows:


		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.

		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_.


		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_.

		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.

	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.
	An 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.


		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 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.


		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.

	You can also construct ref that starts from the first segment to navigate to different path of the same root.
	You can also construct a ref that starts from the first segment to navigate to different path of the same root.

[Java] Document references #2153

Are you sure you want to change the base?

[Java] Document references #2153

Conversation

vmikhailenko commented Oct 15, 2025

Uh oh!

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

renejeglinsky commented Nov 5, 2025

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

renejeglinsky Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot Nov 6, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment