From 9828ad7b3371eb248c85dd78332e8c03f3fbd0c1 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Sat, 26 Oct 2024 10:30:51 +0200
Subject: [PATCH] document performance implications of id batching i.e.
 BatchSize

Signed-off-by: Gavin King <gavin@hibernate.org>
---
 .../src/main/java/org/hibernate/BatchSize.java       | 11 +++++++++++
 .../org/hibernate/MultiIdentifierLoadAccess.java     | 12 ++++++++++++
 .../src/main/java/org/hibernate/Session.java         | 11 ++++++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/hibernate-core/src/main/java/org/hibernate/BatchSize.java b/hibernate-core/src/main/java/org/hibernate/BatchSize.java
index cf982b6ad1..1c848dc59d 100644
--- a/hibernate-core/src/main/java/org/hibernate/BatchSize.java
+++ b/hibernate-core/src/main/java/org/hibernate/BatchSize.java
@@ -23,6 +23,17 @@ import java.util.List;
  * If an explicit batch size is set manually, care should be taken
  * to not exceed the capabilities of the underlying database.
  * <p>
+ * The performance impact of setting a batch size depends on whether
+ * a SQL array may be used to pass the list of identifiers to the
+ * database:
+ * <ul>
+ * <li>for databases which support standard SQL arrays, a smaller
+ *     batch size might be extremely inefficient compared to a very
+ *     large batch size or no batching at all, but
+ * <li>on the other hand, for databases with no SQL array type, a
+ *     large batch size results in long SQL statements with many JDBC
+ *     parameters.
+ * <p>
  * A batch size is considered a hint. This option has no effect
  * on {@link Session#find(Class, Object, FindOption...)}.
  *
diff --git a/hibernate-core/src/main/java/org/hibernate/MultiIdentifierLoadAccess.java b/hibernate-core/src/main/java/org/hibernate/MultiIdentifierLoadAccess.java
index bab6eb4db9..657b4fcb31 100644
--- a/hibernate-core/src/main/java/org/hibernate/MultiIdentifierLoadAccess.java
+++ b/hibernate-core/src/main/java/org/hibernate/MultiIdentifierLoadAccess.java
@@ -133,6 +133,18 @@ public interface MultiIdentifierLoadAccess<T> {
 	 * If an explicit batch size is set manually, care should be taken
 	 * to not exceed the capabilities of the underlying database.
 	 * <p>
+	 * The performance impact of setting a batch size depends on whether
+	 * a SQL array may be used to pass the list of identifiers to the
+	 * database:
+	 * <ul>
+	 * <li>for databases which support standard SQL arrays, a smaller
+	 *     batch size might be extremely inefficient compared to a very
+	 *     large batch size or no batching at all, but
+	 * <li>on the other hand, for databases with no SQL array type, a
+	 *     large batch size results in long SQL statements with many JDBC
+	 *     parameters.
+	 * </ul>
+	 * <p>
 	 * A batch size is considered a hint.
 	 *
 	 * @param batchSize The batch size
diff --git a/hibernate-core/src/main/java/org/hibernate/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java
index b4ff373e27..669e0b16ae 100644
--- a/hibernate-core/src/main/java/org/hibernate/Session.java
+++ b/hibernate-core/src/main/java/org/hibernate/Session.java
@@ -562,7 +562,16 @@ public interface Session extends SharedSessionContract, EntityManager {
 	 * given entity class, or a fully-fetched proxy object.
 	 * <p>
 	 * This method accepts {@link BatchSize} as an option, allowing control over the number of
-	 * records retrieved in a single database request.
+	 * records retrieved in a single database request. The performance impact of setting a batch
+	 * size depends on whether a SQL array may be used to pass the list of identifiers to the
+	 * database:
+	 * <ul>
+	 * <li>for databases which {@linkplain org.hibernate.dialect.Dialect#supportsStandardArrays
+	 *     support standard SQL arrays}, a smaller batch size might be extremely inefficient
+	 *     compared to a very large batch size or no batching at all, but
+	 * <li>on the other hand, for databases with no SQL array type, a large batch size results
+	 *     in long SQL statements with many JDBC parameters.
+	 * </ul>
 	 * <p>
 	 * For more advanced cases, use {@link #byMultipleIds(Class)}, which returns an instance of
 	 * {@link MultiIdentifierLoadAccess}.