Docs for typed result APIs #2006

beckermarc · 2025-08-05T15:05:31Z

No description provided.

agoerler · 2025-08-06T07:01:14Z

cds/cdl.md

@@ -849,7 +849,7 @@ SELECT.from({ ref: [{ id: 'UsingView', args: { bar: { val: true }}} ]} )
 ```
 ```Java [Java]
 var params = Map.of("bar", true);
-Result result = service.run(Select.from("UsingView"), params);
+CdsResult<?> result = service.run(Select.from("UsingView"), params);


This change is not so nice.

agoerler · 2025-08-12T12:16:18Z

java/cds-data.md

@@ -219,7 +219,7 @@ In CAP Java data is represented in maps. To simplify data access in custom code,

 ![This graphic is explained in the accompanying text.](./assets/accessor.drawio.svg)

-The `Row`s of a [query result](./working-with-cql/query-execution#result) as well as the [generated accessor interfaces](#generated-accessor-interfaces) already extend `CdsData`. Using the helper class [Struct](#struct) you can extend any `Map<String, Object>` with the CdsData `interface`:
+The rows of a [query result](./working-with-cql/query-execution#result) as well as the [generated accessor interfaces](#generated-accessor-interfaces) already extend `CdsData`. Using the helper class [Struct](#struct) you can extend any `Map<String, Object>` with the CdsData `interface`:


Suggested change

The rows of a [query result](./working-with-cql/query-execution#result) as well as the [generated accessor interfaces](#generated-accessor-interfaces) already extend `CdsData`. Using the helper class [Struct](#struct) you can extend any `Map<String, Object>` with the CdsData `interface`:

The rows of a [query result](./working-with-cql/query-execution#result) as well as the [generated accessor interfaces](#generated-accessor-interfaces) already extend `CdsData`. Using the helper class [Struct](#struct) you can access any `Map<String, Object>` with the CdsData `interface`:

agoerler · 2025-08-12T12:17:41Z

java/cds-data.md

@@ -307,7 +307,7 @@ You can use the functions, `CQL.cosineSimilarity` or `CQL.l2Distance` (Euclidean
 ```Java
 CqnVector v = CQL.vector(embedding);

-Result similarBooks = service.run(Select.from(BOOKS).where(b ->
+CdsResult<?> similarBooks = service.run(Select.from(BOOKS).where(b ->


Suggested change

CdsResult<?> similarBooks = service.run(Select.from(BOOKS).where(b ->

CdsResult<Books> similarBooks = service.run(Select.from(BOOKS).where(b ->

?

agoerler · 2025-08-12T12:18:14Z

java/cds-data.md

@@ -322,7 +322,7 @@ CqnSelect query = Select.from(BOOKS)
  .where(b -> b.ID().ne(bookId).and(similarity.gt(0.9)))
  .orderBy(b -> b.get("similarity").desc());

-Result similarBooks = db.run(select, CdsVector.of(embedding));
+CdsResult<?> similarBooks = db.run(select, CdsVector.of(embedding));


Suggested change

CdsResult<?> similarBooks = db.run(select, CdsVector.of(embedding));

CdsResult<Books> similarBooks = db.run(select, CdsVector.of(embedding));

?

agoerler · 2025-08-12T12:19:19Z

java/developing-applications/testing.md

@@ -154,7 +154,7 @@ public class CatalogServiceTest {

    @Test
    public void discountApplied() {
-        Result result = catalogService.run(Select.from(Books_.class).byId("51061ce3-ddde-4d70-a2dc-6314afbcc73e"));
+        CdsResult<?> result = catalogService.run(Select.from(Books_.class).byId("51061ce3-ddde-4d70-a2dc-6314afbcc73e"));


Suggested change

CdsResult<?> result = catalogService.run(Select.from(Books_.class).byId("51061ce3-ddde-4d70-a2dc-6314afbcc73e"));

CdsResult<Books> result = catalogService.run(Select.from(Books_.class).byId("51061ce3-ddde-4d70-a2dc-6314afbcc73e"));

agoerler · 2025-08-12T12:20:10Z

java/event-handlers/index.md

    return db.run(context.getCqn());
 }
 ```

 In case an event handler method of the `Before` or `On` phase has a return value it automatically [completes the event processing](#eventcompletion), once it's executed.
 Event handler methods of the `After` phase that have a return value, replace the return value of the event.

-For [CRUD events](../cqn-services/application-services#crudevents) and [draft-specific CRUD events](../fiori-drafts#draftevents), return values that extend `Iterable<? extends Map<String, Object>>` are supported. The `Result` object or a list of entity data (for example `List<Books>`) fulfill this requirement.
+For [CRUD events](../cqn-services/application-services#crudevents) and [draft-specific CRUD events](../fiori-drafts#draftevents), return values that extend `Iterable<? extends Map<String, Object>>` are supported. The `Result` and `CdsResult<?` interfaces or a list of entity data (for example `List<Books>`) fulfill this requirement.


Suggested change

For [CRUD events](../cqn-services/application-services#crudevents) and [draft-specific CRUD events](../fiori-drafts#draftevents), return values that extend `Iterable<? extends Map<String, Object>>` are supported. The `Result` and `CdsResult<?` interfaces or a list of entity data (for example `List<Books>`) fulfill this requirement.

For [CRUD events](../cqn-services/application-services#crudevents) and [draft-specific CRUD events](../fiori-drafts#draftevents), return values that extend `Iterable<? extends Map<String, Object>>` are supported. The `Result` and `CdsResult<?>` interfaces or a list of entity data (for example `List<Books>`) fulfill this requirement.

agoerler · 2025-08-12T12:20:39Z

java/event-handlers/request-contexts.md

@@ -300,7 +300,7 @@ To propagate the parent context, create an instance of `RequestContextRunner` in

 ```java
 RequestContextRunner runner = runtime.requestContext();
-Future<Result> result = Executors.newSingleThreadExecutor().submit(() -> {
+Future<CdsResult<?>> result = Executors.newSingleThreadExecutor().submit(() -> {


Suggested change

Future<CdsResult<?>> result = Executors.newSingleThreadExecutor().submit(() -> {

Future<CdsResult<Books>> result = Executors.newSingleThreadExecutor().submit(() -> {

agoerler · 2025-08-12T12:25:07Z

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

@@ -710,6 +715,19 @@ Map<String, String> titleToDescription =

 For the entities defined in the data model, CAP Java SDK can generate interfaces for you through [a Maven plugin](../cqn-services/persistence-services#staticmodel).

+When setting `linkedInterfaces` to `true` in the CDS Maven Plugin `generate` goal, [query builder interfaces](../working-with-cql/query-api#concepts) and [data accessor interfaces](../cds-data#typed-access) are linked. This enables automatically typed results when executing a `Select` or `Update` statement, avoiding the need to explicitly pass the data accessor interface class to methods like `single()`, `listOf()` or `streamOf()`.


Suggested change

When setting `linkedInterfaces` to `true` in the CDS Maven Plugin `generate` goal, [query builder interfaces](../working-with-cql/query-api#concepts) and [data accessor interfaces](../cds-data#typed-access) are linked. This enables automatically typed results when executing a `Select` or `Update` statement, avoiding the need to explicitly pass the data accessor interface class to methods like `single()`, `listOf()` or `streamOf()`.

When setting `linkedInterfaces` to `true` in the CDS Maven Plugin's `generate` goal, [query builder interfaces](../working-with-cql/query-api#concepts) and [data accessor interfaces](../cds-data#typed-access) are linked. This enables automatically typed results when executing a `Select` or `Update` statement, avoiding the need to explicitly pass the data accessor interface class to methods like `single(Class)`, `listOf(Class)` or `streamOf(Class)`.

agoerler · 2025-08-12T12:26:43Z

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

+```java
+import static cds.gen.catalogservice.CatalogService_.BOOKS;
+
+var select = Select.from(BOOKS).byId(4711); // use var or Select<Books_>


Suggested change

var select = Select.from(BOOKS).byId(4711); // use var or Select<Books_>

Select<Books_> select = Select.from(BOOKS).byId(4711);

agoerler · 2025-08-12T12:28:06Z

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

+```
+
+::: tip
+Avoid using `CqnSelect` or `CqnUpdate` for typed query declarations, but prefer `var` to allow the Java compiler to retain the entity query type, linking to the data accessor interface.


Suggested change

Avoid using `CqnSelect` or `CqnUpdate` for typed query declarations, but prefer `var` to allow the Java compiler to retain the entity query type, linking to the data accessor interface.

Avoid using `CqnSelect` or `CqnUpdate` for typed query declarations, but prefer `var` to allow the Java compiler to retain the entity query type, linking to the data accessor interface: `var result = service.run(select);`

agoerler · 2025-08-12T12:37:10Z

java/cds-data.md

@@ -397,7 +397,7 @@ To select the mapping elements of a managed association, simply add the [associa
 CqnSelect select = Select.from(BOOKS).byId(123)
                         .columns(b -> b.author());

-Row row = persistence.run(select).single();
+CdsData row = persistence.run(select).single();


Suggested change

CdsData row = persistence.run(select).single();

Row row = persistence.run(select).single();

run(CqnSelect) -> Result; Result.single() -> Row

agoerler · 2025-08-12T12:37:46Z

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

@@ -528,7 +528,7 @@ import static bookshop.Bookshop_.BOOKS;
 CqnSelect q = Select.from(BOOKS)
    .columns(b -> b.author());

-Row book = dataStore.execute(q).single();
+CdsData book = dataStore.execute(q).single();


Suggested change

CdsData book = dataStore.execute(q).single();

Row book = dataStore.execute(q).single();

agoerler · 2025-08-12T12:38:48Z

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

@@ -1152,7 +1152,7 @@ Map<String, Object> paramSet2 = new HashMap<>();
 paramSet2.put("author.name", "Emily Brontë");
 paramSet2.put("title", "Wuthering Heights");

-Result result = service.run(update, asList(paramSet1, paramSet2));
+CdsResult<?> result = service.run(update, asList(paramSet1, paramSet2));


Suggested change

CdsResult<?> result = service.run(update, asList(paramSet1, paramSet2));

Result result = service.run(update, asList(paramSet1, paramSet2));

run(CqnUpdate) -> Result

agoerler · 2025-08-12T12:39:09Z

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

@@ -23,7 +23,7 @@ CqnService service = ...
 CqnSelect query = Select.from("bookshop.Books")
    .columns("title", "price");

-Result result = service.run(query);
+CdsResult<?> result = service.run(query);


Suggested change

CdsResult<?> result = service.run(query);

Result result = service.run(query);

agoerler · 2025-08-12T12:44:08Z

java/cds-data.md

@@ -414,7 +414,7 @@ Map<String, Object> order = new HashMap<>();
 order.put("header.status", "canceled");

 CqnSelect select = Select.from("bookshop.Orders").matching(order);
-Result canceledOrders = persistence.run(select);
+CdsResult<?> canceledOrders = persistence.run(select);


Suggested change

CdsResult<?> canceledOrders = persistence.run(select);

Result canceledOrders = persistence.run(select);

agoerler · 2025-08-12T12:58:00Z

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

@@ -81,12 +81,12 @@ CqnDelete delete = Delete.from("bookshop.Books").byParams("ID");
 Map<String, Object> paramSet1 = singletonMap("ID", 101);
 Map<String, Object> paramSet1 = singletonMap("ID", 102);

-Result result = service.run(query, asList(paramSet1, paramSet2));
+CdsResult<?> result = service.run(query, asList(paramSet1, paramSet2));


Suggested change

CdsResult<?> result = service.run(query, asList(paramSet1, paramSet2));

Result result = service.run(query, asList(paramSet1, paramSet2));

agoerler · 2025-08-12T12:58:20Z

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

@@ -114,7 +114,7 @@ To query `BooksView` in Java, run a select statement and provide values for all
 CqnSelect query = Select.from("BooksView");
 var params = Map.of("minStock", 100);

-Result result = service.run(query, params);
+CdsResult<?> result = service.run(query, params);


Suggested change

CdsResult<?> result = service.run(query, params);

Result result = service.run(query, params);

agoerler · 2025-08-12T12:58:39Z

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

@@ -140,12 +140,12 @@ The [update](./query-api) operation can be executed as follows:
 Map<String, Object> book = Map.of("title", "CAP");

 CqnUpdate update = Update.entity("bookshop.Books").data(book).byId(101);
-Result updateResult = service.run(update);
+CdsResult<?> updateResult = service.run(update);


Suggested change

CdsResult<?> updateResult = service.run(update);

Result updateResult = service.run(update);

agoerler · 2025-08-12T12:58:50Z

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

 ```

-The update `Result` contains the data that is written by the statement execution. Additionally to the given data, it may contain values generated for [managed data](../../guides/domain-modeling#managed-data) and foreign key values.
+The update `CdsResult` contains the data that is written by the statement execution. Additionally to the given data, it may contain values generated for [managed data](../../guides/domain-modeling#managed-data) and foreign key values.


Suggested change

The update `CdsResult` contains the data that is written by the statement execution. Additionally to the given data, it may contain values generated for [managed data](../../guides/domain-modeling#managed-data) and foreign key values.

The update `Result` contains the data that is written by the statement execution. Additionally to the given data, it may contain values generated for [managed data](../../guides/domain-modeling#managed-data) and foreign key values.

agoerler · 2025-08-12T13:01:23Z

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

@@ -527,7 +527,7 @@ List<Order> orders = db.run(select).listOf(Order.class);

 orders.forEach(o -> o.setStatus("cancelled"));

-Result rs = db.execute(Update.entity(ORDER).entries(orders));
+CdsResult<?> rs = db.execute(Update.entity(ORDER).entries(orders));


Suggested change

CdsResult<?> rs = db.execute(Update.entity(ORDER).entries(orders));

CdsResult<Order> rs = db.execute(Update.entity(ORDER).entries(orders));

Docs for typed result APIs

c3d749f

beckermarc requested review from agoerler and MattSchur August 5, 2025 15:05

beckermarc requested a review from smahati as a code owner August 5, 2025 15:05

Fix links

f875bf0

agoerler reviewed Aug 12, 2025

View reviewed changes

	The rows of a [query result](./working-with-cql/query-execution#result) as well as the [generated accessor interfaces](#generated-accessor-interfaces) already extend `CdsData`. Using the helper class [Struct](#struct) you can extend any `Map<String, Object>` with the CdsData `interface`:
	The rows of a [query result](./working-with-cql/query-execution#result) as well as the [generated accessor interfaces](#generated-accessor-interfaces) already extend `CdsData`. Using the helper class [Struct](#struct) you can access any `Map<String, Object>` with the CdsData `interface`:

	CdsResult<?> similarBooks = service.run(Select.from(BOOKS).where(b ->
	CdsResult<Books> similarBooks = service.run(Select.from(BOOKS).where(b ->

	CdsResult<?> similarBooks = db.run(select, CdsVector.of(embedding));
	CdsResult<Books> similarBooks = db.run(select, CdsVector.of(embedding));

	CdsResult<?> result = catalogService.run(Select.from(Books_.class).byId("51061ce3-ddde-4d70-a2dc-6314afbcc73e"));
	CdsResult<Books> result = catalogService.run(Select.from(Books_.class).byId("51061ce3-ddde-4d70-a2dc-6314afbcc73e"));

	For [CRUD events](../cqn-services/application-services#crudevents) and [draft-specific CRUD events](../fiori-drafts#draftevents), return values that extend `Iterable<? extends Map<String, Object>>` are supported. The `Result` and `CdsResult<?` interfaces or a list of entity data (for example `List<Books>`) fulfill this requirement.
	For [CRUD events](../cqn-services/application-services#crudevents) and [draft-specific CRUD events](../fiori-drafts#draftevents), return values that extend `Iterable<? extends Map<String, Object>>` are supported. The `Result` and `CdsResult<?>` interfaces or a list of entity data (for example `List<Books>`) fulfill this requirement.

	Future<CdsResult<?>> result = Executors.newSingleThreadExecutor().submit(() -> {
	Future<CdsResult<Books>> result = Executors.newSingleThreadExecutor().submit(() -> {

		@@ -710,6 +715,19 @@ Map<String, String> titleToDescription =

		For the entities defined in the data model, CAP Java SDK can generate interfaces for you through [a Maven plugin](../cqn-services/persistence-services#staticmodel).

		When setting `linkedInterfaces` to `true` in the CDS Maven Plugin `generate` goal, [query builder interfaces](../working-with-cql/query-api#concepts) and [data accessor interfaces](../cds-data#typed-access) are linked. This enables automatically typed results when executing a `Select` or `Update` statement, avoiding the need to explicitly pass the data accessor interface class to methods like `single()`, `listOf()` or `streamOf()`.

	var select = Select.from(BOOKS).byId(4711); // use var or Select<Books_>
	Select<Books_> select = Select.from(BOOKS).byId(4711);

	Avoid using `CqnSelect` or `CqnUpdate` for typed query declarations, but prefer `var` to allow the Java compiler to retain the entity query type, linking to the data accessor interface.
	Avoid using `CqnSelect` or `CqnUpdate` for typed query declarations, but prefer `var` to allow the Java compiler to retain the entity query type, linking to the data accessor interface: `var result = service.run(select);`

	CdsData row = persistence.run(select).single();
	Row row = persistence.run(select).single();

	CdsData book = dataStore.execute(q).single();
	Row book = dataStore.execute(q).single();

	CdsResult<?> result = service.run(update, asList(paramSet1, paramSet2));
	Result result = service.run(update, asList(paramSet1, paramSet2));

	CdsResult<?> result = service.run(query);
	Result result = service.run(query);

	CdsResult<?> canceledOrders = persistence.run(select);
	Result canceledOrders = persistence.run(select);

	CdsResult<?> result = service.run(query, asList(paramSet1, paramSet2));
	Result result = service.run(query, asList(paramSet1, paramSet2));

	CdsResult<?> result = service.run(query, params);
	Result result = service.run(query, params);

	CdsResult<?> updateResult = service.run(update);
	Result updateResult = service.run(update);

	The update `CdsResult` contains the data that is written by the statement execution. Additionally to the given data, it may contain values generated for [managed data](../../guides/domain-modeling#managed-data) and foreign key values.
	The update `Result` contains the data that is written by the statement execution. Additionally to the given data, it may contain values generated for [managed data](../../guides/domain-modeling#managed-data) and foreign key values.

	CdsResult<?> rs = db.execute(Update.entity(ORDER).entries(orders));
	CdsResult<Order> rs = db.execute(Update.entity(ORDER).entries(orders));

Docs for typed result APIs #2006

Are you sure you want to change the base?

Docs for typed result APIs #2006

Uh oh!

Conversation

beckermarc commented Aug 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!