MONGOID-5590 Update sharding docs re: keys with "." characters in them

[jamis]

MONGOID-5582 updated Mongoid so that shard keys with "." in them are treated as delimited fields identifying attributes of embedded subdocuments. This precludes the possibility of using shard keys that literally contain the "." character. Since we've decided this design decision is acceptable, this PR updates the sharding documentation for Mongoid to mention this caveat.

Once accepted, I'll backport this PR to 7.5-stable, 8.0-stable, and 8.1-stable (which were also updated for MONGOID-5582).

ref: https://jira.mongodb.org/browse/MONGOID-5590

[johnnyshields]

Does MongoDB allow . in shard key names? The server docs says that leading $ is not allowed, but is ambiguous about .. It might be good to clarify the server documentation here:
https://www.mongodb.com/docs/v5.2/core/dot-dollar-considerations/

[jamis]

I've not tried it, @johnnyshields, but my reading of that page suggests that only dollar-prefixed names are forbidden as shard key names. Either way, this ticket is concerned specifically with Mongoid, and we've made the decision to disallow "." characters in shard key names there.

[johnnyshields]

Hmmm... wouldn't it make sense to check it? Are there tests which cover the documented behavior here? At first glance I couldn't find any tests that have a shard key containing .

Sharding is pretty dangerous if done wrong, so it makes sense to be extra cautious here esp. if Mongoid docs advertising a certain behavior.

[johnnyshields]

Ah oops sorry I see you added the tests in MONGOID-5582

Looking at the API of the server, if . is interpreted to mean "embedded field traversal" as per your tests, then it would seem that it would be impossible to use a literal dot in the field name. AFAIK Mongoid's shard_key is passed verbatim to the MongoDB API shardCollection() -> key field https://www.mongodb.com/docs/manual/core/sharding-shard-a-collection/

Server team should clarify this... raised a ticket here: https://jira.mongodb.org/browse/DOCS-15993