MONGOID-5019 Document omitting _id field from embedded documents (#4931)

Co-authored-by: Oleg Pudeyev <oleg@bsdpower.com>

Author: p-mongo

source/tutorials/mongoid-documents.txt

@@ -804,19 +804,58 @@ To define the field anyway, use the ``overwrite: true`` option:
   end
 
 
+.. _custom-id:
+
 Custom Ids
 ----------
 
-For cases when you do not want to have ``BSON::ObjectId`` ids, you can override Mongoid's
-``_id`` field and set them to whatever you like.
+By default, Mongoid defines the ``_id`` field on documents to contain a
+``BSON::ObjcetId`` value which is automatically generated by Mongoid.
+
+It is possible to replace the ``_id`` field definition to change the type
+of the ``_id`` values or have different default values:
 
 .. code-block:: ruby
 
-   class Band
-     include Mongoid::Document
-     field :name, type: String
-     field :_id, type: String, default: ->{ name }
-   end
+  class Band
+    include Mongoid::Document
+    field :name, type: String
+    field :_id, type: String, default: ->{ name }
+  end
+
+It is possible to omit the default entirely:
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :_id, type: String
+  end
+
+If the default on ``_id`` is omitted, and no ``_id`` value is provided by
+your application, Mongoid will persist the document without the ``_id``
+value and one will be assigned by the server. However, Mongoid will
+not automatically retrieve this value when the document is persisted - you
+must obtain the persisted value (and the complete persisted document) using
+other means:
+
+.. code-block:: ruby
+
+  band = Band.create!
+  => #<Band _id: , >
+  band.id
+  => nil
+  band.reload
+  # raises Mongoid::Errors::DocumentNotFound
+  Band.last
+  => #<Band _id: 5fc681c22c97a6791f324b99, >
+
+Omitting ``_id`` fields is more common in :ref:`embedded documents <omit-id>`.
+
+Mongoid also defines the ``id`` field aliased to ``_id``. The ``id``
+alias can :ref:`be removed <unalias-id>` if desired (such as to integrate
+with systems that use the ``id`` field to store value different from ``_id``.
+
 
 .. _bson-symbol:
 

source/tutorials/mongoid-relations.txt

@@ -702,6 +702,39 @@ The following deviations are known:
 In general, Mongoid adopts the behavior of current server versions and validates more strictly.
 
 
+.. _omit-id:
+
+Omitting ``_id`` Fields
+-----------------------
+
+By default, Mongoid adds an ``_id`` field to each embedded document. This
+permits easy referencing of and operations on the embedded documents.
+
+These ``_id`` fields may be omitted to save storage space. To do so,
+:ref:`override the _id field definition in the child documents <custom-id>`
+and remove the default value:
+
+.. code-block:: ruby
+
+  class Order
+    include Mongoid::Document
+    
+    embeds_many :line_items
+  end
+  
+  class LineItem
+    include Mongoid::Document
+    
+    embedded_in :order
+    
+    field :_id, type: Object
+  end
+
+In the current version of Mongoid the field definition is required, but
+without a default value specified no value will be stored in the database.
+A future version of Mongoid may allow removing previously defined fields.
+
+
 Common Behavior
 ===============