Description

The context is someone (me) with more SQL than Mongo experience. I think more should be done to warn about the risks of:
1) using a subdocument as the value of _id
2) searching by value for a subdocument, whether or not there is an index

I think this is important because not doing this correctly means a user can get incorrect query results – either data won't be found or wrong data will be returned.

https://docs.mongodb.com/manual/tutorial/query-embedded-documents/ states
"Equality matches on the whole embedded document require an exact match of the specified <value> document, including the field order."
... but does not explain that whether field order can be guaranteed is driver dependent

This page has examples but no warnings about the driver dependency
https://docs.mongodb.com/manual/reference/method/db.collection.find/#query-embedded-documents

This page has examples and a brief warning about field order without mentioning the driver dependency:
https://docs.mongodb.com/manual/core/index-single/#create-an-index-on-embedded-document
"When performing equality matches on embedded documents, field order matters and the embedded documents must match exactly"

By driver dependency I mean that the client encodes BSON and there must be a way for clients to enforce the order in which fields will be encoded. I assume that Son does this for Python. The SON doc page is vague about why key order matters:
[https://api.mongodb.com/python/current/api/bson/son.html
]"Regular dictionaries can be used instead of SON objects, but not when the order of keys is important."

This page has a great description of the problem and solution. I hope something like it can be mentioned in the manual.
https://emptysqua.re/blog/pymongo-key-order

And one of our co-workers has a nice answer at https://softwareengineering.stackexchange.com/questions/319468/why-does-mongodb-check-for-order-of-keys-when-matching-embedded-documents

Scope of changes

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)