[Spring Data Cosmos] Fix GROUP BY aggregate query exception (#43912)

sdk/spring/azure-spring-data-cosmos/CHANGELOG.md

@@ -8,6 +8,8 @@
 
 #### Bugs Fixed
 
+* Fixed `IllegalArgumentException: Entity is null` when using `@Query` with GROUP BY aggregates returning non-entity types (`ObjectNode`, `Map`, custom DTOs) - See [Bug #43912](https://github.com/Azure/azure-sdk-for-java/issues/43912).
+
 #### Other Changes
 
 ### 7.1.0 (2026-03-11)

sdk/spring/azure-spring-data-cosmos/src/main/java/com/azure/spring/data/cosmos/core/convert/MappingCosmosConverter.java

@@ -75,7 +75,15 @@ public MappingCosmosConverter(
 
     @Override
     public <R> R read(Class<R> type, JsonNode jsonNode) {
-        final CosmosPersistentEntity<?> entity = mappingContext.getPersistentEntity(type);
+        CosmosPersistentEntity<?> entity = null;
+        try {
+            entity = mappingContext.getPersistentEntity(type);
+        } catch (Exception e) {
+            // Non-entity types (ObjectNode, Map, DTOs) cannot be introspected by the
+            // mapping context. Fall through with null entity to use direct Jackson
+            // deserialization in readInternal. (GitHub #43912)
+            LOGGER.debug("No persistent entity found for type {}, using direct deserialization", type.getName());
+        }
         return readInternal(entity, type, jsonNode);
     }
 
@@ -91,7 +99,12 @@ private <R> R readInternal(final CosmosPersistentEntity<?> entity, Class<R> type
                 return objectMapper.treeToValue(jsonNode, type);
             }
 
-            Assert.notNull(entity, "Entity is null.");
+            // When the return type is not a Cosmos-mapped entity (e.g., ObjectNode, Map, DTO),
+            // mappingContext.getPersistentEntity() returns null. Fall back to direct Jackson
+            // deserialization, bypassing entity-specific id/etag remapping. (GitHub #43912)
+            if (entity == null) {
+                return objectMapper.treeToValue(jsonNode, type);
+            }
             final ObjectNode objectNode = jsonNode.deepCopy();
             final CosmosPersistentProperty idProperty = entity.getIdProperty();
             final JsonNode idValue = jsonNode.get("id");

sdk/spring/azure-spring-data-cosmos/src/test/java/com/azure/spring/data/cosmos/core/converter/MappingCosmosConverterUnitTest.java

@@ -7,6 +7,7 @@
 import com.azure.spring.data.cosmos.core.convert.ObjectMapperFactory;
 import com.azure.spring.data.cosmos.core.mapping.CosmosMappingContext;
 import com.azure.spring.data.cosmos.domain.Address;
+import com.azure.spring.data.cosmos.domain.AggregateDto;
 import com.azure.spring.data.cosmos.domain.BigJavaMathTypes;
 import com.azure.spring.data.cosmos.domain.Importance;
 import com.azure.spring.data.cosmos.domain.Memo;
@@ -25,6 +26,7 @@
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.Date;
+import java.util.Map;
 import java.util.UUID;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -177,5 +179,57 @@ public void mapsDefaultEtag() {
 
         assertThat(jsonNode.get(TestConstants.PROPERTY_ETAG_DEFAULT).asText()).isEqualTo(etagValue);
     }
+
+    // Tests for GitHub #43912 — GROUP BY aggregates with non-entity return types
+
+    @Test
+    public void readObjectNodeFromJsonNodeSucceeds() {
+        final ObjectNode objectNode = ObjectMapperFactory.getObjectMapper().createObjectNode();
+        objectNode.put("id_count", 5);
+        objectNode.put("intValue", 42);
+
+        final ObjectNode result = mappingCosmosConverter.read(ObjectNode.class, objectNode);
+
+        assertThat(result).isNotNull();
+        assertThat(result.get("id_count").asInt()).isEqualTo(5);
+        assertThat(result.get("intValue").asInt()).isEqualTo(42);
+    }
+
+    @Test
+    @SuppressWarnings("unchecked")
+    public void readMapFromJsonNodeSucceeds() {
+        final ObjectNode objectNode = ObjectMapperFactory.getObjectMapper().createObjectNode();
+        objectNode.put("num_ids", 3);
+        objectNode.put("department", "engineering");
+
+        final Map<String, Object> result = mappingCosmosConverter.read(Map.class, objectNode);
+
+        assertThat(result).isNotNull();
+        assertThat(result.get("num_ids")).isEqualTo(3);
+        assertThat(result.get("department")).isEqualTo("engineering");
+    }
+
+    @Test
+    public void readPlainDtoFromJsonNodeSucceeds() {
+        final ObjectNode objectNode = ObjectMapperFactory.getObjectMapper().createObjectNode();
+        objectNode.put("count", 7);
+        objectNode.put("label", "group-a");
+
+        final AggregateDto result = mappingCosmosConverter.read(AggregateDto.class, objectNode);
+
+        assertThat(result).isNotNull();
+        assertThat(result.getCount()).isEqualTo(7);
+        assertThat(result.getLabel()).isEqualTo("group-a");
+    }
+
+    @Test
+    public void readObjectFromJsonNodeSucceeds() {
+        final ObjectNode objectNode = ObjectMapperFactory.getObjectMapper().createObjectNode();
+        objectNode.put("key", "value");
+
+        final Object result = mappingCosmosConverter.read(Object.class, objectNode);
+
+        assertThat(result).isNotNull();
+    }
 }
 

sdk/spring/azure-spring-data-cosmos/src/test/java/com/azure/spring/data/cosmos/domain/AggregateDto.java

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.azure.spring.data.cosmos.domain;
+
+/**
+ * Simple DTO for testing non-entity deserialization of GROUP BY aggregate query results.
+ * Not annotated with @Container — intentionally a plain POJO (GitHub #43912).
+ */
+public class AggregateDto {
+    private int count;
+    private String label;
+
+    public AggregateDto() {
+    }
+
+    public AggregateDto(int count, String label) {
+        this.count = count;
+        this.label = label;
+    }
+
+    public int getCount() {
+        return count;
+    }
+
+    public void setCount(int count) {
+        this.count = count;
+    }
+
+    public String getLabel() {
+        return label;
+    }
+
+    public void setLabel(String label) {
+        this.label = label;
+    }
+}