MONGOID-5161 - [Documentation Only] Clarify the policy for working with . and $ named fields which were introduced in MongoDB 5.0

docs/README.md

@@ -7,6 +7,8 @@ tutorials and the reference.
 To build the documentation locally for review, install `sphinx` and
 `sphinx-book-theme`, then execute `make html` in this directory:
 
-    pip install sphinx sphinx-book-theme
+    pip install 'sphinx<4.3' sphinx-book-theme
     make html
 
+Note: sphinx 4.3 is currently breaking when trying to render Mongoid
+documentation.

docs/reference/fields.txt

@@ -13,6 +13,8 @@ Field Definition
    :class: singlecol
 
 
+.. _field-types:
+
 Field Types
 ===========
 
@@ -1151,3 +1153,48 @@ you can include the short versions of the modules.
      include Mongoid::Document
      include Mongoid::Timestamps::Updated::Short # For u_at only.
    end
+
+
+.. _field-names-with-periods-and-dollar-signs:
+
+Field Names with Dots/Periods (``.``) and Dollar Signs (``$``)
+==============================================================
+
+MongoDB query language (MQL) generally uses the dot/period character (``.``)
+to separate field names in a field path that traverses embedded documents, and
+the dollar character (``$``) for operators. It is possible to utilize field
+names containing the dot and dollar characters, however it is recommended to
+avoid these characters for ease of querying.
+
+MongoDB 5.0 adds `special operators
+<https://docs.mongodb.com/manual/core/dot-dollar-considerations/#std-label-crud-concepts-dot-dollar-considerations>`_
+for querying and modifying documents using field names containing dots and
+dollars. Previous MongoDB versions do not provide a mechanism for querying
+documents on fields whose names contain dots and dollars, though such documents
+can be retrieved verbatim (once they are matched using some other strategy).
+
+Mongoid provides its own DSL for querying MongoDB and, unlike MongoDB 5.0,
+Mongoid does not yet provide any facilities for querying documents using
+field names containing dots and dollars. It is possible to query such documents
+using MQL, but not via most Mongoid DSL methods. Additionally, there is
+other code in Mongoid that assumes that the dot (``.``) separates path
+components which may misbehave should a document contain a field with dots
+in its name.
+
+Historically, MongoDB drivers prohibited inserting documents with field names
+containing dots and dollars, since such documents couldn't be queried via
+those field names. This prohibition is now being lifted due to the new
+operators introduced with MongoDB 5.0; however, the required changes in the
+Ruby driver `have not yet been implemented
+<https://jira.mongodb.org/browse/RUBY-2528>`_. By virtue of using the Ruby
+driver to interact with the database, this prohibition on inserting documents
+with field names containing dots and dollars also applies to Mongoid.
+Thus, while both the Ruby driver and Mongoid permit querying documents that
+have been inserted using other mechanisms by field names containing dots and
+dollars, there is presently no possibility to insert such documents using
+either Ruby driver or Mongoid.
+
+To summarize, field names containing dots and dollars have limited support in
+Mongoid, the Ruby MongoDB driver and MongoDB server. Such field names should
+only be used when interfacing with software that already uses these names,
+and should be avoided for new development.