Documentation

src/main/asciidoc/jdbc.adoc

@@ -471,6 +471,33 @@ This process also applies to inserting new aggregates, where a `null` or `0` ver
 
 During deletes the version check also applies but no version is increased.
 
+[[jdbc.loading-aggregates]]
+== Loading Aggregates
+Spring Data JDBC offers two ways how it can load aggregates.
+The traditional and before version 3.2 the only way is really simple:
+Each query loads the aggregate roots, independently if the query is based on a `CrudRepository` method, a derived query or a annotated query.
+If the aggregate root references other entities those are loaded with separate statements.
+
+Spring Data JDBC now allows the use of _Single Query Loading_.
+With this an arbitrary number of aggregates can be fully loaded with a single SQL query.
+This should be significant more efficient, especially for complex aggregates, consisting of many entities.
+
+Currently this feature is very restricted.
+
+1. It only works for aggregates that only reference one entity collection. The plan is to remove this constraint in the future.
+
+2. The aggregate must also not use `AggregateReference` or embedded entities. The plan is to remove this constraint in the future.
+
+3. The database dialect must support it. Of the dialects provided by Spring Data JDBC all but H2 and HSQL support this. H2 and HSQL don't support analytic functions (aka windowing functions).
+
+4. It only works for the find methods in `CrudRepository`, not for derived queries and not for annotated queries. The plan is to remove this constraint in the future.
+
+5. Single Query Loading needs to be enabled in the `JdbcMappingContext`, by calling `setSingleQueryLoadingEnabled(true)`
+
+Note: Single Query Loading is to be considered experimental. We appreciate feedback on how it works for you.
+
+Note:Single Query Loading can be abbreviated as SQL, but we highly discourage that since confusion with Structured Query Language is almost guaranteed.
+
 [[jdbc.query-methods]]
 == Query Methods