Merge pull request #4697 from MicrosoftDocs/copilot/warn-optional-query-compatibility

prmerger-automator[bot] · web-flow · commit 2298c1f447ca · 2026-04-06T12:36:21.000Z
Add warning: @query methods cannot return Optional<T>
diff --git a/articles/cosmos-db/quickstart-java.md b/articles/cosmos-db/quickstart-java.md
@@ -235,6 +235,9 @@ public interface ItemRepository extends CosmosRepository<Item, String> {
 }
 ```
 
+> [!IMPORTANT]
+> `@Query`-annotated methods must return `List<T>` or a single `T`, not `Optional<T>`. `Optional<T>` is only supported for derived query methods such as `findById`. Using `Optional<T>` with `@Query` compiles without errors but causes a `ClassCastException` at runtime.
+
 Fetch all of the results of the query using `repository.getItemsByCategory`. Loop through the results of the query.
 
 ```java

Original file line number	Diff line number	Diff line change
`@@ -235,6 +235,9 @@ public interface ItemRepository extends CosmosRepository<Item, String> {`
`235`	`235`	`}`
`236`	`236`	```
`237`	`237`
	`238`	`+> [!IMPORTANT]`
	`239`	+> `@Query`-annotated methods must return `List<T>` or a single `T`, not `Optional<T>`. `Optional<T>` is only supported for derived query methods such as `findById`. Using `Optional<T>` with `@Query` compiles without errors but causes a `ClassCastException` at runtime.
	`240`	`+`
`238`	`241`	Fetch all of the results of the query using `repository.getItemsByCategory`. Loop through the results of the query.
`239`	`242`
`240`	`243`	```java