JAVA-2062: Document frozen collection preference with Mapper

changelog/README.md

@@ -2,8 +2,9 @@
 
 ### 3.7.0 (In progress)
 
-- [improvement] JAVA-2025: Include exception message in Abstract*Codec.accepts(null).
+- [improvement] JAVA-2025: Include exception message in Abstract\*Codec.accepts(null).
 - [improvement] JAVA-1980: Use covariant return types in RemoteEndpointAwareJdkSSLOptions.Builder methods.
+- [documentation] JAVA-2062: Document frozen collection preference with Mapper.
 
 
 ### 3.6.0

manual/object_mapper/creating/README.md

@@ -363,6 +363,26 @@ private Map<String, List<Address>> frozenValueMap;
 [frozenkey]:http://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/mapping/annotations/FrozenKey.html
 [frozenvalue]:http://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/mapping/annotations/FrozenValue.html
 
+#### Prefer Frozen Collections
+
+If `Mapper.save` is used to create and update entities, it is recommended to
+use frozen collections over non-frozen collections.
+
+Frozen collections in Cassandra are serialized as a single cell value where
+non-frozen collections serialize each individual element in a collection as a
+cell.
+
+Since `Mapper.save` provides the entire collection for an entity field value on
+each invocation, it is more efficient to use frozen collections as the entire
+collection is serialized as one cell.
+
+Also, when using non-frozen collections, on INSERT Cassandra must
+create a tombstone to invalidate all existing collection elements, even if
+there are none. When using frozen collections, no such tombstone is needed.
+
+See [Freezing collection types] for more information about the frozen keyword.
+
+[Freezing collection types]: https://docs.datastax.com/en/dse/6.7/cql/cql/cql_using/refCollectionType.html
 
 ### Polymorphism support