From 8c5fd0ad0c615194ade9571966a6de4d8074ab0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adrian=20G=C3=B6rler?= Date: Fri, 17 Jan 2025 17:54:19 +0100 Subject: [PATCH 1/2] structured query results --- java/working-with-cql/query-api.md | 115 ++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 1 deletion(-) diff --git a/java/working-with-cql/query-api.md b/java/working-with-cql/query-api.md index 365b74bcd..e22b6010b 100644 --- a/java/working-with-cql/query-api.md +++ b/java/working-with-cql/query-api.md @@ -514,6 +514,119 @@ Both queries are equivalent and have the same result: a _flat_ structure: + +#### Structured Results + +Use [inline](#inline), [expand](#expand), and aliases to influence the structure of the query result. + +##### Dot-separated Paths + +You can create a _structured_ query result using a _dot-separated_ path as alias. In the follwing CDS model the elements `firstName` and `lastName` are on top-level in the `Person` entity: + +```cds +entity Person { + id : Int32; + firstName : String; + lastName : String +} +``` + +Use this query to return the elements in a substructure `name`: + +```java +Select.from(PERSON) + .columns(p -> p.Id(), + p -> p.firstName().as("name.first"), + p -> p.lastName().as("name.last")); +``` + +A result row will have this structure: + +```json +{ + "id" : 1, + "name" : { + "first" : "Sam", + "last" : "Cook" + } +} +``` + +On the select list, you can use a _dot-separated_ path to select an element of an associated entity, which will be [inlined](#inline) + +```java +Select.from("bookshop.Books") + .columns("title", "author.name"); +``` + +giving you a flat result: + +```json +{ + "title" : "Dracula", + "name" : "Bram Stroker" +} +``` + +If you want to preserve the structure and rather have the author's name in a dedicated author object you can do an [expand](#expand): + +```java +Select.from("bookshop.Books") + .columns(b -> b.get("title"), + b -> b.to("author").expand("name")); +``` + +-> + +```json +{ + "title" : "Dracula", + "author" : { + "name" : "Bram Stroker" + } +} +``` + +To preserve structure, you can also use a _dot-separated_ path on the select list combined with a _dot-separated_ alias: + +```java +Select.from("bookshop.Books") + .columns(b -> b.get("title"), + b -> b.get("author.name").as("author.name")); +``` + +-> + +```json +{ + "title" : "Dracula", + "author" : { + "name" : "Bram Stroker" + } +} +``` + +##### Space-separated Paths + +For convenience, you can use a _space-separated_ path to reference an element of an associated entity. It will then be select preserving the structure: + +```java +Select.from("bookshop.Books") + .columns("title", + "author name"); // space-separated path (!) +``` + +-> + +```json +{ + "title" : "Dracula", + "author" : { + "name" : "Bram Stroker" + } +} +``` + #### Managed Associations on the Select List To select the key elements of a [managed to-one association](../../cds/cdl#managed-associations)'s target entity, simply put the association on the select list. This will return the target key elements as structured result: @@ -530,7 +643,7 @@ CqnSelect q = Select.from(BOOKS) .columns(b -> b.author()); Row book = dataStore.execute(q).single(); -Object authorId = book.get("author.Id"); // path access +Object authorId = book.getPath("author.Id"); // path access ``` ::: tip From ae8edc1edd0f3e959b09fb64ad08d17f498b9dce Mon Sep 17 00:00:00 2001 From: Mahati Shankar Date: Thu, 30 Jan 2025 13:45:39 +0100 Subject: [PATCH 2/2] cosmetics --- java/working-with-cql/query-api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/java/working-with-cql/query-api.md b/java/working-with-cql/query-api.md index e22b6010b..67b3bcda8 100644 --- a/java/working-with-cql/query-api.md +++ b/java/working-with-cql/query-api.md @@ -521,7 +521,7 @@ Use [inline](#inline), [expand](#expand), and aliases to influence the structure ##### Dot-separated Paths -You can create a _structured_ query result using a _dot-separated_ path as alias. In the follwing CDS model the elements `firstName` and `lastName` are on top-level in the `Person` entity: +You can create a _structured_ query result using a _dot-separated_ path as an alias. In the following CDS model the elements `firstName` and `lastName` are on top-level in the `Person` entity: ```cds entity Person { @@ -540,7 +540,7 @@ Select.from(PERSON) p -> p.lastName().as("name.last")); ``` -A result row will have this structure: +The resulting row structure: ```json { @@ -552,14 +552,14 @@ A result row will have this structure: } ``` -On the select list, you can use a _dot-separated_ path to select an element of an associated entity, which will be [inlined](#inline) +You can select an associated entity's element by adding its _dot-separated_ path in the list. The result includes the value [inlined](#inline) at the top-level. ```java Select.from("bookshop.Books") .columns("title", "author.name"); ``` -giving you a flat result: +Giving you a flat result: ```json { @@ -568,7 +568,7 @@ giving you a flat result: } ``` -If you want to preserve the structure and rather have the author's name in a dedicated author object you can do an [expand](#expand): +If you want to preserve the structure and rather have the author's name in a dedicated author object, use [expand](#expand): ```java Select.from("bookshop.Books") @@ -608,7 +608,7 @@ Select.from("bookshop.Books") ##### Space-separated Paths -For convenience, you can use a _space-separated_ path to reference an element of an associated entity. It will then be select preserving the structure: +For convenience, you can use a _space-separated_ path to reference an element of an associated entity: ```java Select.from("bookshop.Books")