feat: add projection and map support for aggregations (#539)

Implements Spring Data-style projections and map-based results for aggregations,
providing flexible alternatives to tuple-based results. Follows Spring Data
conventions where IDs are not automatically included in projections.

- Add toProjection(Class<P>) method for interface-based projections
- Add toMaps() and toMaps(boolean includeId) for map-based results
- Projections follow Spring Data JPA pattern (IDs not auto-included)
- Maps include IDs by default with option to exclude
- Dynamic proxy implementation for projection interfaces
- Type conversion support for common types
- Comprehensive tests for both document and hash entities
- Documentation with examples and comparison of approaches

Author: bsbodden

docs/content/modules/ROOT/pages/entity-streams-aggregations.adoc

@@ -299,6 +299,154 @@ entityStream.of(Person.class)
     });
 ----
 
+== Projections and Maps
+
+Redis OM Spring supports projections and map-based results for aggregations, providing flexible ways to work with aggregated data.
+
+=== Interface-Based Projections
+
+You can define projection interfaces to shape your aggregation results. IDs are not automatically included - add `getId()` to your projection if needed.
+
+[source,java]
+----
+import static com.redis.om.spring.annotations.ReducerFunction.*;
+
+// Define projection interface
+public interface DepartmentStatsProjection {
+    Integer getDepartmentNumber();
+    Long getHeadcount();
+    Double getTotalSales();
+    // String getId();  // Uncomment only if ID is needed
+}
+
+// Use projection with aggregation
+List<DepartmentStatsProjection> stats = entityStream.of(Person.class)
+    .groupBy(Person$.DEPARTMENT_NUMBER)
+    .reduce(COUNT).as("headcount")
+    .reduce(SUM, Person$.SALES).as("totalSales")
+    .sorted(Order.desc("@totalSales"))
+    .toProjection(DepartmentStatsProjection.class);
+
+// Access data through interface methods
+stats.forEach(stat -> {
+    System.out.printf("Dept %d: %d employees, $%.2f total sales%n",
+        stat.getDepartmentNumber(), 
+        stat.getHeadcount(), 
+        stat.getTotalSales());
+});
+----
+
+=== Simple Field Projections
+
+For simpler use cases, create projections for specific fields:
+
+[source,java]
+----
+import static com.redis.om.spring.annotations.ReducerFunction.*;
+
+public interface NameProjection {
+    String getName();
+    Long getCount();
+}
+
+// Get just names from aggregation with count
+List<NameProjection> names = entityStream.of(Person.class)
+    .groupBy(Person$.NAME)
+    .reduce(COUNT).as("count")
+    .toProjection(NameProjection.class);
+----
+
+=== Map-Based Results
+
+For maximum flexibility, convert aggregation results to Maps. By default, IDs are included.
+
+[source,java]
+----
+import static com.redis.om.spring.annotations.ReducerFunction.*;
+import java.util.Map;
+
+// Get results as maps with IDs included
+List<Map<String, Object>> results = entityStream.of(Person.class)
+    .groupBy(Person$.DEPARTMENT_NUMBER)
+    .reduce(COUNT).as("count")
+    .reduce(AVG, Person$.SALES).as("avgSales")
+    .toMaps();
+
+// Each map contains the aggregated data
+results.forEach(map -> {
+    System.out.printf("Dept %s: %d employees, avg sales $%.2f%n",
+        map.get("departmentNumber"),
+        map.get("count"),
+        map.get("avgSales"));
+});
+
+// Exclude IDs if not needed
+List<Map<String, Object>> resultsNoId = entityStream.of(Person.class)
+    .groupBy(Person$.NAME)
+    .reduce(SUM, Person$.SALES)
+    .toMaps(false);  // IDs excluded
+----
+
+=== Projection vs Maps vs Tuples
+
+Choose the right approach for your use case:
+
+[source,java]
+----
+import static com.redis.om.spring.annotations.ReducerFunction.*;
+import java.util.Map;
+
+// 1. Projections - Type-safe, IDE support, best for defined structures
+public interface SalesProjection {
+    String getName();
+    Double getTotalSales();
+}
+
+List<SalesProjection> projections = entityStream.of(Person.class)
+    .groupBy(Person$.NAME)
+    .reduce(SUM, Person$.SALES).as("totalSales")
+    .toProjection(SalesProjection.class);
+
+// 2. Maps - Flexible, dynamic fields, good for variable structures
+List<Map<String, Object>> maps = entityStream.of(Person.class)
+    .groupBy(Person$.NAME)
+    .reduce(SUM, Person$.SALES).as("totalSales")
+    .toMaps();
+
+// 3. Tuples - Lightweight, positional access, existing approach
+List<Pair<String, Double>> tuples = entityStream.of(Person.class)
+    .groupBy(Person$.NAME)
+    .reduce(SUM, Person$.SALES)
+    .toList(String.class, Double.class);
+----
+
+=== Complex Projections
+
+Projections can handle complex aggregation results:
+
+[source,java]
+----
+import static com.redis.om.spring.annotations.ReducerFunction.*;
+
+public interface ComprehensiveStats {
+    Integer getDepartmentNumber();
+    Long getEmployeeCount();
+    Double getMinSales();
+    Double getMaxSales();
+    Double getAvgSales();
+    Double getTotalSales();
+}
+
+List<ComprehensiveStats> stats = entityStream.of(Person.class)
+    .groupBy(Person$.DEPARTMENT_NUMBER)
+    .reduce(COUNT).as("employeeCount")
+    .reduce(MIN, Person$.SALES).as("minSales")
+    .reduce(MAX, Person$.SALES).as("maxSales")
+    .reduce(AVG, Person$.SALES).as("avgSales")
+    .reduce(SUM, Person$.SALES).as("totalSales")
+    .toProjection(ComprehensiveStats.class);
+----
+
 == Performance Considerations
 
 === Efficient Aggregations

docs/content/modules/ROOT/pages/entity-streams.adoc

@@ -271,6 +271,8 @@ List<Integer> foundingYears = entityStream.of(Company.class)
     .collect(Collectors.toList());
 ----
 
+NOTE: For more advanced projection capabilities, including interface-based projections and map results, see xref:entity-streams-aggregations.adoc#_projections_and_maps[Projections and Maps in Aggregations].
+
 === Multiple Field Projections
 
 Create tuples for multiple field projections:

docs/content/modules/ROOT/pages/overview.adoc

@@ -2,25 +2,25 @@
 :page-toclevels: 3
 :page-pagination:
 
-Redis OM Spring is a comprehensive advanced object-mapping, querying and repositories framework for Spring applications using Redis, it extends and enhances Spring Data Redis. While Spring Data Redis provides basic Redis functionality, Redis OM Spring delivers a complete solution designed specifically to leverage the advanced features of Redis 8+, Redis Enterprise, and Redis Cloud.
+Redis OM Spring is a comprehensive advanced object-mapping, querying and repositories framework for Spring applications using Redis, it extends and enhances Spring Data Redis. While Spring Data Redis provides basic Redis functionality, Redis OM Spring delivers a complete solution designed specifically to leverage the advanced features of Redis 8+ (and a few older Redis Stack distros), Redis Enterprise, and Redis Cloud.
 
 == What is Redis OM Spring?
 
-Redis OM Spring is an Object Mapping framework designed specifically for Redis, allowing Java developers to work with Redis data using familiar annotations and repository patterns. Redis OM Spring reimagines how Redis should integrate with Spring applications to provide a more intuitive and powerful developer experience.
+Redis OM Spring is an Object Mapping framework designed specifically for Redis, allowing Java developers to work with Redis data using  annotations, repository patterns, fluid Streams-like APIs and more. Redis OM Spring reimagines how Redis should integrate with Spring applications to provide a more intuitive and powerful developer experience.
 
 image::redis-om-spring-architecture.png[Redis OM Spring Architecture,width=100%]
 
 [.lead]
 Redis OM Spring consists of two modules:
 
 * *redis-om-spring* - Core module providing modeling, indexing, search, and repository capabilities
-* *redis-om-spring-ai* - AI module offering vector embedding generation through Spring AI integration
+* *redis-om-spring-ai* - AI module offering AI-focused features like vector embedding generation - it leverages Spring AI
 
 == Redis Integration
 
 Redis OM Spring is built to work with Redis 8.0.0+, which includes these essential capabilities:
 
-* *Query Engine* - Powerful search and query engine (formerly RediSearch)
+* *Query Engine* - Powerful search / query engine with Full-text and Vector capabilities (formerly RediSearch)
 * *JSON* - Native JSON document storage 
 * *Probabilistic Data Structures* - Bloom filters, Cuckoo filters, and more
 * *Auto-Complete* - Fast auto-complete server-side functionality
@@ -153,9 +153,12 @@ public class MyDoc {
 * Type-safe query construction with generated metamodels
 * Fluent filtering, sorting, and projection
 * Powerful aggregation capabilities with grouping and reduction
+* Interface-based projections and map results for aggregations
 
 [source,java]
 ----
+import static com.redis.om.spring.annotations.ReducerFunction.*;
+
 // Find companies founded between 1980 and 2020, sorted by name
 List<Company> companies = entityStream
     .of(Company.class)
@@ -167,7 +170,7 @@ List<Company> companies = entityStream
 List<Pair<String, Long>> topBrands = entityStream
     .of(Game.class)
     .groupBy(Game$.BRAND)
-    .reduce(ReducerFunction.COUNT).as("count")
+    .reduce(COUNT).as("count")
     .sorted(Order.desc("@count"))
     .limit(5)
     .toList(String.class, Long.class);
@@ -176,12 +179,26 @@ List<Pair<String, Long>> topBrands = entityStream
 List<Quintuple<String, Double, Double, Double, Long>> priceStats = entityStream
     .of(Game.class)
     .groupBy(Game$.BRAND)
-    .reduce(ReducerFunction.AVG, Game$.PRICE).as("avgPrice")
-    .reduce(ReducerFunction.MIN, Game$.PRICE).as("minPrice")
-    .reduce(ReducerFunction.MAX, Game$.PRICE).as("maxPrice")
-    .reduce(ReducerFunction.COUNT).as("count")
+    .reduce(AVG, Game$.PRICE).as("avgPrice")
+    .reduce(MIN, Game$.PRICE).as("minPrice")
+    .reduce(MAX, Game$.PRICE).as("maxPrice")
+    .reduce(COUNT).as("count")
     .sorted(Order.desc("@count"))
     .toList(String.class, Double.class, Double.class, Double.class, Long.class);
+
+// Interface-based projections for aggregations
+public interface BrandStats {
+    String getBrand();
+    Double getAvgPrice();
+    Long getCount();
+}
+
+List<BrandStats> brandStatistics = entityStream
+    .of(Game.class)
+    .groupBy(Game$.BRAND)
+    .reduce(AVG, Game$.PRICE).as("avgPrice")
+    .reduce(COUNT).as("count")
+    .toProjection(BrandStats.class);
 ----
 
 === Aggregation Support

docs/content/modules/ROOT/pages/query-annotation.adoc

@@ -192,6 +192,8 @@ SearchResult getFirstTag();
 SearchResult customFindAllByTitleStartingWithReturnFieldsAndLimit(@Param("prefix") String prefix);
 ----
 
+NOTE: For more advanced projection capabilities, including interface-based projections with type safety, see xref:entity-streams-aggregations.adoc#_projections_and_maps[Projections and Maps in Aggregations].
+
 === Pagination
 
 Control the number of results with Spring Data Pageable or annotation attributes:

docs/content/modules/ROOT/pages/repository-queries.adoc

@@ -217,6 +217,31 @@ public interface CompanyRepository extends RedisDocumentRepository<Company, Stri
 }
 ----
 
+== Working with Projections
+
+Redis OM Spring supports Spring Data projections for efficient data retrieval:
+
+=== Interface-Based Projections
+
+Define an interface with getter methods for the fields you need:
+
+[source,java]
+----
+// Define projection interface
+public interface CompanyProjection {
+    String getName();
+    Integer getYearFounded();
+    // Note: ID is not automatically included
+}
+
+// Use in repository - requires custom implementation
+public interface CompanyRepository extends RedisDocumentRepository<Company, String> {
+    List<CompanyProjection> findByPubliclyListed(boolean publiclyListed);
+}
+----
+
+NOTE: Projection support in repositories requires custom implementation. For built-in projection support, use Entity Streams with aggregations. See xref:entity-streams-aggregations.adoc#_projections_and_maps[Projections and Maps in Aggregations].
+
 == Best Practices
 
 * Use the appropriate query method for your needs
@@ -229,4 +254,5 @@ public interface CompanyRepository extends RedisDocumentRepository<Company, Stri
 
 * xref:query-annotation.adoc[Query Annotation]
 * xref:entity-streams.adoc[Entity Streams]
+* xref:entity-streams-aggregations.adoc[Entity Streams Aggregations]
 * xref:qbe.adoc[Query By Example]

redis-om-spring/src/main/java/com/redis/om/spring/search/stream/AggregationStream.java

@@ -2,6 +2,7 @@
 
 import java.time.Duration;
 import java.util.List;
+import java.util.Map;
 
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
@@ -238,6 +239,38 @@ public interface AggregationStream<T> {
    */
   <R extends T> List<R> toList(Class<?>... contentTypes);
 
+  /**
+   * Executes the aggregation and converts the results to a list of projection objects.
+   * The projection interface should define getter methods for the fields to include.
+   * IDs are not automatically included - add getId() to the projection interface if needed.
+   * 
+   * @param <P>             the projection type
+   * @param projectionClass the projection interface class
+   * @return a list of projection instances with the aggregated data
+   * @throws RuntimeException if the aggregation execution or projection creation fails
+   */
+  <P> List<P> toProjection(Class<P> projectionClass);
+
+  /**
+   * Executes the aggregation and converts the results to a list of maps.
+   * Each map contains field names as keys and field values as values.
+   * By default, entity IDs are included in the results.
+   * 
+   * @return a list of maps containing the aggregated data with IDs included
+   * @throws RuntimeException if the aggregation execution fails
+   */
+  List<Map<String, Object>> toMaps();
+
+  /**
+   * Executes the aggregation and converts the results to a list of maps.
+   * Each map contains field names as keys and field values as values.
+   * 
+   * @param includeId whether to include entity IDs in the results
+   * @return a list of maps containing the aggregated data
+   * @throws RuntimeException if the aggregation execution fails
+   */
+  List<Map<String, Object>> toMaps(boolean includeId);
+
   /**
    * Returns the underlying RediSearch query that would be executed.
    * This is useful for debugging and understanding the generated query.