MONGOID-4812 Allow id to be a regular field in models (not an alias of _id) (#4929)

* unalias id/_id

* remove other traces of aliasing

* keep aliased fields

* create a method to unalias an attribute

* remove whitespace

* make #only more straightforward & efficient

* extract Criteria#only tests in their own file

* verify only works correctly when id is unaliased

* note that aliases are not included

* rename the test because I will add without to it

* move #without tests to projection

* fix #without when id is unaliased

* test cases for using #without when id is unaliased

* Document #without

* Note that id cannot be omitted via without

* basic integration test

* clean up

* add docstring

* remove extra whitespace

* add tutorial documentation

* use _id instead of id everywhere in the codebase

* add an upgrading note

* fix cloning

* fix nested_one association

Co-authored-by: Emily Giurleo <[email protected]>
Co-authored-by: Oleg Pudeyev <[email protected]>

Author: 3 people

source/tutorials/mongoid-documents.txt

@@ -591,30 +591,89 @@ the other attributes are set, use the ``pre_processed: true`` field option:
     pre_processed: true
 
 
+.. _storage-field-names:
+
+Specifying Storage Field Names
+------------------------------
+
+One of the drawbacks of having a schemaless database is that MongoDB must
+store all field information along with every document, meaning that it
+takes up a lot of storage space in RAM and on disk. A common pattern to limit
+this is to alias fields to a small number of characters, while keeping the
+domain in the application expressive. Mongoid allows you to do this and
+reference the fields in the domain via their long names in getters, setters,
+and criteria while performing the conversion for you.
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :n, as: :name, type: String
+  end
+
+  band = Band.new(name: "Placebo")
+  band.attributes # { "n" => "Placebo" }
+
+  criteria = Band.where(name: "Placebo")
+  criteria.selector # { "n" => "Placebo" }
+
+
 .. _field-aliases:
 
-Aliasing Fields
----------------
+Field Aliases
+-------------
 
-One of the drawbacks of having a schemaless database is that MongoDB must store all field
-information along with every document, meaning that it takes up a lot of storage space in RAM
-and on disk. A common pattern to limit this is to alias fields to a small number of characters,
-while keeping the domain in the application expressive. Mongoid allows you to do this and
-reference the fields in the domain via their long names in getters, setters, and criteria while
-performing the conversion for you.
+It is possible to define field aliases. The value will be stored in the
+destination field but can be accessed from either the destination field or
+from the aliased field:
 
 .. code-block:: ruby
 
-   class Band
-     include Mongoid::Document
-     field :n, as: :name, type: String
-   end
+  class Band
+    include Mongoid::Document
+    
+    field :name, type: String
+    alias_attribute :n, :name
+  end
+  
+  band = Band.new(n: 'Astral Projection')
+  # => #<Band _id: 5fc1c1ee2c97a64accbeb5e1, name: "Astral Projection">
+  
+  band.attributes
+  # => {"_id"=>BSON::ObjectId('5fc1c1ee2c97a64accbeb5e1'), "name"=>"Astral Projection"}
+  
+  band.n
+  # => "Astral Projection"
+
+Aliases can be removed from model classes using the ``unalias_attribute``
+method.
+
+.. code-block:: ruby
+
+  class Band
+    unalias_attribute :n
+  end
+
+.. _unalias-id:
+
+Unaliasing ``id``
+`````````````````
 
-   band = Band.new(name: "Placebo")
-   band.attributes # { "n" => "Placebo" }
+``unalias_attribute`` can be used to remove the predefined ``id`` alias.
+This is useful for storing different values in ``id`` and ``_id`` fields:
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+    
+    unalias_attribute :id
+    field :id, type: String
+  end
+  
+  Band.new(id: '42')
+  # => #<Band _id: 5fc1c3f42c97a6590684046c, id: "42">
 
-   criteria = Band.where(name: "Placebo")
-   criteria.selector # { "n" => "Placebo" }
 
 Custom Fields
 -------------

source/tutorials/mongoid-queries.txt

@@ -223,7 +223,8 @@ the query:
 Aliases
 ```````
 
-Queries take into account :ref:`field aliases <field-aliases>`:
+Queries take into account :ref:`storage field names <storage-field-names>`
+and :ref:`field aliases <field-aliases>`:
 
 .. code-block:: ruby
 
@@ -730,6 +731,9 @@ as the following example shows:
 Projection
 ----------
 
+``only``
+````````
+
 The ``only`` method retrieves only the specified fields from the database. This
 operation is sometimes called "projection".
 
@@ -831,6 +835,42 @@ loaded with ``only`` for those associations to be loaded. For example:
   Band.where(name: 'Astral Projection').only(:name, :manager_ids).first.managers
   # => [#<Manager _id: 5c5dc2f0026d7c1730969843, band_ids: [BSON::ObjectId('5c5dc2f0026d7c1730969842')]>]
 
+``without``
+```````````
+
+The opposite of ``only``, ``without`` causes the specified fields to be omitted:
+
+.. code-block:: ruby
+
+  Band.without(:name)
+  # => 
+  # #<Mongoid::Criteria
+  #   selector: {}
+  #   options:  {:fields=>{"name"=>0}}
+  #   class:    Band
+  #   embedded: false>
+
+Because Mongoid requires the ``_id`` field for various operations, it (as well
+as its ``id`` alias) cannot be omitted via ``without``:
+
+.. code-block:: ruby
+
+  Band.without(:name, :id)
+  # => 
+  # #<Mongoid::Criteria
+  #   selector: {}
+  #   options:  {:fields=>{"name"=>0}}
+  #   class:    Band
+  #   embedded: false>
+
+  Band.without(:name, :_id)
+  # => 
+  # #<Mongoid::Criteria
+  #   selector: {}
+  #   options:  {:fields=>{"name"=>0}}
+  #   class:    Band
+  #   embedded: false>
+
 
 Ordering
 --------

source/tutorials/mongoid-upgrade.txt

@@ -209,6 +209,12 @@ New Embedded Matching Operators
 Mongoid 7.3 adds support for bitwise operators, ``$comment``, ``$mod`` and
 ``$type`` operators when :ref:`embedded matching <embedded-matching>`.
 
+Unaliasing ``id`` Field
+-----------------------
+
+It is now possible to :ref:`remove the id alias in models <unalias-id>`,
+to make ``id`` a regular field.
+
 
 Upgrading to Mongoid 7.2
 ========================