DATAMONGO-2341 - Support shard key derivation in save operations via @Sharded annotation.

Spring Data MongoDB uses the @Sharded annotation to identify entities stored in sharded collections.
The shard key consists of a single or multiple properties present in every document within the target collection, and is used to distribute them across shards.

Spring Data MongoDB will do best effort optimisations for sharded scenarios when using repositories by adding required shard key information, if not already present, to replaceOne filter queries when upserting entities. This may require an additional server round trip to determine the actual value of the current shard key.

By setting @Sharded(immutableKey = true) no attempt will be made to check if an entities shard key changed.

Please see the MongoDB Documentation for further details and the list below for which operations are eligible to auto include the shard key.

* Reactive/CrudRepository.save(...)
* Reactive/CrudRepository.saveAll(...)
* Reactive/MongoTemplate.save(...)

Original pull request: #833.

src/main/asciidoc/index.adoc

@@ -30,6 +30,7 @@ include::reference/reactive-mongo-repositories.adoc[leveloffset=+1]
 include::{spring-data-commons-docs}/auditing.adoc[leveloffset=+1]
 include::reference/mongo-auditing.adoc[leveloffset=+1]
 include::reference/mapping.adoc[leveloffset=+1]
+include::reference/sharding.adoc[leveloffset=+1]
 include::reference/kotlin.adoc[leveloffset=+1]
 include::reference/cross-store.adoc[leveloffset=+1]
 include::reference/jmx.adoc[leveloffset=+1]

src/main/asciidoc/reference/sharding.adoc

@@ -0,0 +1,70 @@
+[[sharding]]
+= Sharding
+
+MongoDB supports large data sets via sharding, a method for distributing data across multiple machines. Please refer to the https://docs.mongodb.com/manual/sharding/[MongoDB Documentation] to learn how to set up a sharded cluster, its requirements and limitations.
+
+Spring Data MongoDB uses the `@Sharded` annotation to identify entities stored in sharded collections as shown below.
+
+====
+[source, java]
+----
+@Document("users")
+@Sharded(shardKey = { "country", "userId" }) <1>
+public class User {
+
+	@Id
+	Long id;
+
+	@Field("userid")
+	String userId;
+
+	String country;
+}
+----
+<1> The properties of the shard key are mapped to the actual field names. See
+====
+
+[[sharding.sharded-collections]]
+== Sharded Collections
+
+Spring Data MongoDB does not auto set up sharding for collections nor indexes required for it. The snippet below shows how to do so using the MongoDB client API.
+
+====
+[source, java]
+----
+MongoDatabase adminDB = template.getMongoDbFactory()
+    .getMongoDatabase("admin"); <1>
+
+adminDB.runCommand(new Document("enableSharding", "db")); <2>
+
+Document shardCmd = new Document("shardCollection", "db.users") <3>
+	.append("key", new Document("country", 1).append("userid", 1)); <4>
+
+adminDB.runCommand(shardCmd);
+----
+<1> Sharding commands need to be run against the _admin_ database.
+<2> Enable sharding for a specific database if necessary.
+<3> Shard a collection within the database having sharding enabled.
+<4> Set the shard key (Range based sharding in this case).
+====
+
+[[sharding.shard-key]]
+== Shard Key Handling
+
+The shard key consists of a single or multiple properties present in every document within the target collection, and is used to distribute them across shards.
+
+Adding the `@Sharded` annotation to an entity enables Spring Data MongoDB to do best effort optimisations required for sharded scenarios when using repositories.
+This means essentially adding required shard key information, if not already present, to `replaceOne` filter queries when upserting entities. This may require an additional server round trip to determine the actual value of the current shard key.
+
+TIP: By setting `@Sharded(immutableKey = true)` no attempt will be made to check if an entities shard key changed.
+
+Please see the https://docs.mongodb.com/manual/reference/method/db.collection.replaceOne/#upsert[MongoDB Documentation] for further details and the list below for which operations are eligible for auto include the shard key.
+
+* `Reactive/CrudRepository.save(...)`
+* `Reactive/CrudRepository.saveAll(...)`
+* `Reactive/MongoTemplate.save(...)`
+
+
+
+
+