document performance implications of id batching i.e. BatchSize

Signed-off-by: Gavin King <gavin@hibernate.org>

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...)}.
  *

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

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}.