.. _fields:

****************
Field Definition
****************

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol


.. _field-types:

Field Types
===========

MongoDB stores underlying document data using
`BSON types <https://mongodb.com/docs/manual/reference/bson-types/>`_, and
Mongoid converts BSON types to Ruby types at runtime in your application.
For example, a field defined with `type: :float` will use the Ruby ``Float``
class in-memory and will persist in the database as the the BSON ``double`` type.

Field type definitions determine how Mongoid behaves when constructing queries
and retrieving/writing fields from/to the database. Specifically:

1. When assigning values to fields at runtime, the values are converted to the
   specified type.
2. When persisting data to MongoDB, the data is sent in an appropriate
   type, permitting richer data manipulation within MongoDB or by other
   tools.
3. When querying documents, query parameters are converted to the specified
   type before being sent to MongoDB.
4. When retrieving documents from the database, field values are converted
   to the specified type.

Changing the field definitions in a model class does not alter data already stored in
MongoDB. To update type or contents of fields of existing documents,
the field must be re-saved to the database. Note that, due to Mongoid
tracking which attributes on a model change and only saving the changed ones,
it may be necessary to explicitly write a field value when changing the
type of an existing field without changing the stored values.

Consider a simple class for modeling a person in an application. A person may
have a name, date_of_birth, and weight. We can define these attributes
on a person by using the ``field`` macro.

.. code-block:: ruby

   class Person
     include Mongoid::Document
     field :name, type: String
     field :date_of_birth, type: Date
     field :weight, type: Float
   end

The valid types for fields are as follows:

- ``Array``
- ``BSON::Binary``
- :ref:`BigDecimal <field-type-big-decimal>`
- ``Mongoid::Boolean``, which may be specified simply as ``Boolean`` in the
  scope of a class which included ``Mongoid::Document``.
- :ref:`Date <field-type-date>`
- :ref:`DateTime <field-type-date-time>`
- ``Float``
- :ref:`Hash <field-type-hash>`
- ``Integer``
- :ref:`Object <untyped-fields>`
- ``BSON::ObjectId``
- ``Range``
- :ref:`Regexp <field-type-regexp>`
- ``Set``
- ``String``
- :ref:`Mongoid::StringifiedSymbol <field-type-stringified-symbol>`,
  which may be specified simply as ``StringifiedSymbol`` in the scope of a
  class which included ``Mongoid::Document``.
- :ref:`Symbol <field-type-stringified-symbol>`
- :ref:`Time <field-type-time>`
- ``ActiveSupport::TimeWithZone``

Mongoid also recognizes the string ``"Boolean"`` as an alias for the
``Mongoid::Boolean`` class.

To define custom field types, refer to :ref:`Custom Field Types <custom-field-types>` below.

.. note::

  Using the ``BSON::Int64`` and ``BSON::Int32`` types as field types is unsupported.
  Saving these types to the database will work as expected, however, querying them
  will return the native Ruby ``Integer`` type. Querying fields of type
  ``BSON::Decimal128`` will return values of type ``BSON::Decimal128`` in
  BSON <=4 and values of type ``BigDecimal`` in BSON 5+.


.. _untyped-fields:

Untyped Fields
--------------

Not specifying a type for a field is the same as specifying the ``Object``
type. Such fields are untyped:

.. code-block:: ruby

  class Product
    include Mongoid::Document

    field :properties
    # Equivalent to:
    field :properties, type: Object
  end

An untyped field can store values of any type which is directly serializable
to BSON. This is useful when a field may contain values of different types
(i.e. it is a variant type field), or when the type of values is not known
ahead of time:

.. code-block:: ruby

  product = Product.new(properties: "color=white,size=large")
  product.properties
  # => "color=white,size=large"

  product = Product.new(properties: {color: "white", size: "large"})
  product.properties
  # => {:color=>"white", :size=>"large"}

When values are assigned to the field, Mongoid still performs mongoization but
uses the class of the value rather than the field type for mongoization logic.

.. code-block:: ruby

  product = Product.new(properties: 0..10)
  product.properties
  # The range 0..10, mongoized:
  # => {"min"=>0, "max"=>10}

When reading data from the database, Mongoid does not perform any type
conversions on untyped fields. For this reason, even though it is possible
to write any BSON-serializable value into an untyped fields, values which
require special handling on the database reading side will generally not work
correctly in an untyped field. Among field types supported by Mongoid,
values of the following types should not be stored in untyped fields:

- ``Date`` (values will be returned as ``Time``)
- ``DateTime`` (values will be returned as ``Time``)
- ``Range`` (values will be returned as ``Hash``)


.. _field-type-stringified-symbol:

Field Type: StringifiedSymbol
-----------------------------

The ``StringifiedSymbol`` field type is the recommended field type for storing
values that should be exposed as symbols to Ruby applications. When using the ``Symbol`` field type,
Mongoid defaults to storing values as BSON symbols. For more information on the
BSON symbol type, see :ref:`here <field-type-symbol>`.
However, the BSON symbol type is deprecated and is difficult to work with in programming languages
without native symbol types, so the ``StringifiedSymbol`` type allows the use of symbols
while ensuring interoperability with other drivers. The ``StringifiedSymbol`` type stores all data
on the database as strings, while exposing values to the application as symbols.

An example usage is shown below:

.. code-block:: ruby

  class Post
    include Mongoid::Document

    field :status, type: StringifiedSymbol
  end

  post = Post.new(status: :hello)
  # status is stored as "hello" on the database, but returned as a Symbol
  post.status
  # => :hello

  # String values can be assigned also:
  post = Post.new(status: "hello")
  # status is stored as "hello" on the database, but returned as a Symbol
  post.status
  # => :hello

All non-string values will be stringified upon being sent to the database (via ``to_s``), and
all values will be converted to symbols when returned to the application. Values that cannot be
converted directly to symbols, such as integers and arrays, will first be converted to strings and
then symbols before being returned to the application.

For example, setting an integer as ``status``:

.. code-block:: ruby

  post = Post.new(status: 42)
  post.status
  # => :"42"

If the ``StringifiedSymbol`` type is applied to a field that contains BSON symbols, the values
will be stored as strings instead of BSON symbols on the next save. This permits transparent lazy
migration from fields that currently store either strings or BSON symbols in the database to the
``StringifiedSymbol`` field type.


.. _field-type-symbol:

Field Type: Symbol
------------------

New applications should use the :ref:`StringifiedSymbol field type <field-type-stringified-symbol>`
to store Ruby symbols in the database. The ``StringifiedSymbol`` field type
provides maximum compatibility with other applications and programming languages
and has the same behavior in all circumstances.

Mongoid also provides the deprecated ``Symbol`` field type for serializing
Ruby symbols to BSON symbols. Because the BSON specification deprecated the
BSON symbol type, the `bson` gem will serialize Ruby symbols into BSON strings
when used on its own. However, in order to maintain backwards compatibility
with older datasets, the `mongo` gem overrides this behavior to serialize Ruby
symbols as BSON symbols. This is necessary to be able to specify queries for
documents which contain BSON symbols as fields.

To override the default behavior and configure the ``mongo`` gem (and thereby
Mongoid as well) to encode symbol values as strings, include the following code
snippet in your project:

.. code-block:: ruby

  class Symbol
    def bson_type
      BSON::String::BSON_TYPE
    end
  end


.. _field-type-hash:

Field Type: Hash
----------------

When using a field of type Hash, be wary of adhering to the
`legal key names for mongoDB <http://docs.mongodb.org/manual/reference/limits/#naming-restrictions>`_,
or else the values will not store properly.

.. code-block:: ruby

   class Person
     include Mongoid::Document
     field :first_name
     field :url, type: Hash

     # will update the fields properly and save the values
     def set_vals
       self.first_name = 'Daniel'
       self.url = {'home_page' => 'http://www.homepage.com'}
       save
     end

     # all data will fail to save due to the illegal hash key
     def set_vals_fail
       self.first_name = 'Daniel'
       self.url = {'home.page' => 'http://www.homepage.com'}
       save
     end
   end


.. _field-type-time:

Field Type: Time
----------------

``Time`` fields store values as ``Time`` instances in the :ref:`configured
time zone <time-zones>`.

``Date`` and ``DateTime`` instances are converted to ``Time`` instances upon
assignment to a ``Time`` field:

.. code-block:: ruby

  class Voter
    include Mongoid::Document

    field :registered_at, type: Time
  end

  Voter.new(registered_at: Date.today)
  # => #<Voter _id: 5fdd80392c97a618f07ba344, registered_at: 2020-12-18 05:00:00 UTC>

In the above example, the value was interpreted as the beginning of today in
local time, because the application was not configured to use UTC times.

.. note::

  When the database contains a string value for a ``Time`` field, Mongoid
  parses the string value using ``Time.parse`` which considers values without
  time zones to be in local time.


.. _field-type-date:

Field Type: Date
----------------

Mongoid allows assignment of values of several types to ``Date`` fields:

- ``Date`` - the provided date is stored as is.
- ``Time``, ``DateTime``, ``ActiveSupport::TimeWithZone`` - the date component
  of the value is taken in the value's time zone.
- ``String`` - the date specified in the string is used.
- ``Integer``, ``Float`` - the value is taken to be a UTC timestamp which is
  converted to the :ref:`configured time zone <time-zones>` (note that
  ``Mongoid.use_utc`` has no effect on this conversion), then the date is
  taken from the resulting time.

In other words, if a date is specified in the value, that date is used without
first converting the value to the configured time zone.

As a date & time to date conversion is lossy (it discards the time component),
especially if an application operates with times in different time zones it is
recommended to explicitly convert ``String``, ``Time`` and ``DateTime``
objects to ``Date`` objects before assigning the values to fields of type
``Date``.

.. note::

  When the database contains a string value for a ``Date`` field, Mongoid
  parses the string value using ``Time.parse``, discards the time portion of
  the resulting ``Time`` object and uses the date portion. ``Time.parse``
  considers values without time zones to be in local time.


.. _field-type-date-time:

Field Type: DateTime
---------------------

MongoDB stores all times as UTC timestamps. When assigning a value to a
``DateTime`` field, or when querying a ``DateTime`` field, Mongoid
converts the passed in value to a UTC ``Time`` before sending it to the
MongoDB server.

``Time``, ``ActiveSupport::TimeWithZone`` and ``DateTime`` objects embed
time zone information, and the value persisted is the specified moment in
time, in UTC. When the value is retrieved, the time zone in which it is
returned is defined by the :ref:`configured time zone settings <time-zones>`.

.. code-block:: ruby

   class Ticket
     include Mongoid::Document
     field :opened_at, type: DateTime
   end

   Mongoid.use_activesupport_time_zone = true
   Time.zone = 'Berlin'

   ticket = Ticket.create!(opened_at: '2018-02-18 07:00:08 -0500')

    ticket.opened_at
    # => Sun, 18 Feb 2018 13:00:08 +0100
    ticket
    # => #<Ticket _id: 5c13d4b9026d7c4e7870bb2f, opened_at: 2018-02-18 12:00:08 UTC>

    Time.zone = 'America/New_York'
    ticket.opened_at
    # => Sun, 18 Feb 2018 07:00:08 -0500

    Mongoid.use_utc = true
    ticket.opened_at
    # => Sun, 18 Feb 2018 12:00:08 +0000

Mongoid also supports casting integers and floats to ``DateTime``. When
doing so, the integers/floats are assumed to be Unix timestamps (in UTC):

.. code-block:: ruby

    ticket.opened_at = 1544803974
    ticket.opened_at
    # => Fri, 14 Dec 2018 16:12:54 +0000

If a string is used as a ``DateTime`` field value, the behavior depends on
whether the string includes a time zone. If no time zone is specified,
the :ref:`default Mongoid time zone <time-zones>` is used:

.. code-block:: ruby

    Time.zone = 'America/New_York'
    ticket.opened_at = 'Mar 4, 2018 10:00:00'
    ticket.opened_at
    # => Sun, 04 Mar 2018 15:00:00 +0000

If a time zone is specified, it is respected:

.. code-block:: ruby

    ticket.opened_at = 'Mar 4, 2018 10:00:00 +01:00'
    ticket.opened_at
    # => Sun, 04 Mar 2018 09:00:00 +0000

.. note::

  When the database contains a string value for a ``DateTime`` field, Mongoid
  parses the string value using ``Time.parse`` which considers values without
  time zones to be in local time.


.. _field-type-regexp:

Field Type: Regexp
------------------

MongoDB supports storing regular expressions in documents, and querying using
regular expressions. Note that MongoDB uses
`Perl-compatible regular expressions (PCRE) <http://pcre.org/>`_
and Ruby uses `Onigmo <https://github.com/k-takata/Onigmo>`_, which is a
fork of `Oniguruma regular expression engine <https://github.com/kkos/oniguruma>`_.
The two regular expression implementations generally provide equivalent
functionality but have several important syntax differences.

When a field is declared to be of type Regexp, Mongoid converts Ruby regular
expressions to BSON regular expressions and stores the result in MongoDB.
Retrieving the field from the database produces a ``BSON::Regexp::Raw``
instance:

.. code-block:: ruby

  class Token
    include Mongoid::Document

    field :pattern, type: Regexp
  end

  token = Token.create!(pattern: /hello.world/m)
  token.pattern
  # => /hello.world/m

  token.reload
  token.pattern
  # => #<BSON::Regexp::Raw:0x0000555f505e4a20 @pattern="hello.world", @options="ms">

Use ``#compile`` method on ``BSON::Regexp::Raw`` to get back the Ruby regular
expression:

.. code-block:: ruby

  token.pattern.compile
  # => /hello.world/m

Note that, if the regular expression was not originally a Ruby one, calling
``#compile`` on it may produce a different regular expression. For example,
the following is a PCRE matching a string that ends in "hello":

.. code-block:: ruby

  BSON::Regexp::Raw.new('hello$', 's')
  # => #<BSON::Regexp::Raw:0x0000555f51441640 @pattern="hello$", @options="s">

Compiling this regular expression produces a Ruby regular expression that
matches strings containing "hello" before a newline, besides strings ending in
"hello":

.. code-block:: ruby

  BSON::Regexp::Raw.new('hello$', 's').compile =~ "hello\nworld"
  # => 0

This is because the meaning of ``$`` is different between PCRE and Ruby
regular expressions.

.. _field-type-big-decimal:

BigDecimal Fields
-----------------

The ``BigDecimal`` field type is used to store numbers with increased precision.

The ``BigDecimal`` field type stores its values in two different ways in the
database, depending on the value of the ``Mongoid.map_big_decimal_to_decimal128``
global config option. If this flag is set to false (which is the default),
the ``BigDecimal`` field will be stored as a string, otherwise it will be stored
as a ``BSON::Decimal128``.

The ``BigDecimal`` field type has some limitations when converting to and from
a ``BSON::Decimal128``:

- ``BSON::Decimal128`` has a limited range and precision, while ``BigDecimal``
  has no restrictions in terms of range and precision. ``BSON::Decimal128`` has
  a max value of approximately ``10^6145`` and a min value of approximately
  ``-10^6145``, and has a maximum of 34 bits of precision. When attempting to
  store values that don't fit into a ``BSON::Decimal128``, it is recommended to
  have them stored as a string instead of a ``BSON::Decimal128``. You can do
  that by setting ``Mongoid.map_big_decimal_to_decimal128`` to ``false``. If a
  value that does not fit in a ``BSON::Decimal128`` is attempted to be stored
  as one, an error will be raised.

- ``BSON::Decimal128`` is able to accept signed ``NaN`` values, while
  ``BigDecimal`` is not. When retrieving signed ``NaN`` values from
  the database using the ``BigDecimal`` field type, the ``NaN`` will be
  unsigned.

- ``BSON::Decimal128`` maintains trailing zeroes when stored in the database.
  ``BigDecimal``, however, does not maintain trailing zeroes, and therefore
  retrieving ``BSON::Decimal128`` values using the ``BigDecimal`` field type
  may result in a loss of precision.

There is an additional caveat when storing a ``BigDecimal`` in a field with no
type (i.e. a dynamically typed field) and ``Mongoid.map_big_decimal_to_decimal128``
is ``false``. In this case, the ``BigDecimal`` is stored as a string, and since a
dynamic field is being used, querying for that field with a ``BigDecimal`` will
not find the string for that ``BigDecimal``, since the query is looking for a
``BigDecimal``. In order to query for that string, the ``BigDecimal`` must
first be converted to a string with ``to_s``. Note that this is not a problem
when the field has type ``BigDecimal``.

If you wish to avoid using ``BigDecimal`` altogether, you can set the field
type to ``BSON::Decimal128``. This will allow you to keep track of trailing
zeroes and signed ``NaN`` values.

Migration to ``decimal128``-backed ``BigDecimal`` Field
```````````````````````````````````````````````````````
In a future major version of Mongoid, the ``Mongoid.map_big_decimal_to_decimal128``
global config option will be defaulted to ``true``. When this flag is turned on,
``BigDecimal`` values in queries will not match to the strings that are already
stored in the database; they will only match to ``decimal128`` values that are
in the database. If you have a ``BigDecimal`` field that is backed by strings,
you have three options:

1. The ``Mongoid.map_big_decimal_to_decimal128`` global config option can be
   set to ``false``, and you can continue storing your ``BigDecimal`` values as
   strings. Note that you are surrendering the advantages of storing ``BigDecimal``
   values as a ``decimal128``, like being able to do queries and aggregations
   based on the numerical value of the field.

2. The ``Mongoid.map_big_decimal_to_decimal128`` global config option can be
   set to ``true``, and you can convert all values for that field from strings to
   ``decimal128`` values in the database. You should do this conversion before
   setting the global config option to true. An example query to accomplish this
   is as follows:

   .. code-block:: javascript

      db.bands.updateMany({
        "field": { "$exists": true }
      }, [
        {
          "$set": {
            "field": { "$toDecimal": "$field" }
          }
        }
      ])

   This query updates all documents that have the given field, setting that
   field to its corresponding ``decimal128`` value. Note that this query only
   works in MongoDB 4.2+.

3. The ``Mongoid.map_big_decimal_to_decimal128`` global config option can be
   set to ``true``, and you can have both strings and ``decimal128`` values for
   that field. This way, only ``decimal128`` values will be inserted into and
   updated to the database going forward. Note that you still don't get the
   full advantages of using only ``decimal128`` values, but your dataset is
   slowly migrating to all ``decimal128`` values, as old string values are
   updated to ``decimal128`` and new ``decimal128`` values are added. With this
   setup, you can still query for ``BigDecimal`` values as follows:

   .. code-block:: ruby

      Mongoid.map_big_decimal_to_decimal128 = true
      big_decimal = BigDecimal('2E9')
      Band.in(sales: [big_decimal, big_decimal.to_s]).to_a

   This query will find all values that are either a ``decimal128`` value or
   a string that match that value.


Using Symbols Or Strings Instead Of Classes
-------------------------------------------

Mongoid permits using symbols or strings instead of classes to specify the
type of fields, for example:

.. code-block:: ruby

  class Order
    include Mongoid::Document

    field :state, type: :integer
    # Equivalent to:
    field :state, type: "integer"
    # Equivalent to:
    field :state, type: Integer
  end

Only standard field types as listed below can be specified using symbols or
strings in this manner. Mongoid recognizes the following expansions:

- ``:array`` => ``Array``
- ``:big_decimal`` => ``BigDecimal``
- ``:binary`` => ``BSON::Binary``
- ``:boolean`` => ``Mongoid::Boolean``
- ``:date`` => ``Date``
- ``:date_time`` => ``DateTime``
- ``:float`` => ``Float``
- ``:hash`` => ``Hash``
- ``:integer`` => ``Integer``
- ``:object_id`` => ``BSON::ObjectId``
- ``:range`` => ``Range``
- ``:regexp`` => ``Regexp``
- ``:set`` => ``Set``
- ``:string`` => ``String``
- ``:stringified_symbol`` => ``StringifiedSymbol``
- ``:symbol`` => ``Symbol``
- ``:time`` => ``Time``


.. _field-default-values:

Specifying Field Default Values
-------------------------------

A field can be configured to have a default value. The default value can be
fixed, as in the following example:

.. code-block:: ruby

  class Order
    include Mongoid::Document

    field :state, type: String, default: 'created'
  end

The default value can also be specified as a ``Proc``:

.. code-block:: ruby

  class Order
    include Mongoid::Document

    field :fulfill_by, type: Time, default: ->{ Time.now + 3.days }
  end

.. note::

  Default values that are not ``Proc`` instances are evaluated at class load
  time, meaning the following two definitions are not equivalent:

  .. code-block:: ruby

    field :submitted_at, type: Time, default: Time.now
    field :submitted_at, type: Time, default: ->{ Time.now }

  The second definition is most likely the desired one, which causes the
  time of submission to be set to the current time at the moment of
  document instantiation.

To set a default which depends on the document's state, use ``self``
inside the ``Proc`` instance which would evaluate to the document instance
being operated on:

.. code-block:: ruby

  field :fulfill_by, type: Time, default: ->{
    # Order should be fulfilled in 2 business hours.
    if (7..8).include?(self.submitted_at.hour)
      self.submitted_at + 4.hours
    elsif (9..3).include?(self.submitted_at.hour)
      self.submitted_at + 2.hours
    else
      (self.submitted_at + 1.day).change(hour: 11)
    end
  }

When defining a default value as a ``Proc``, Mongoid will apply the default
after all other attributes are set and associations are initialized.
To have the default be applied before the other attributes are set,
use the ``pre_processed: true`` field option:

.. code-block:: ruby

  field :fulfill_by, type: Time, default: ->{ Time.now + 3.days },
    pre_processed: true

The ``pre_processed: true`` option is also necessary when specifying a custom
default value via a ``Proc`` for the ``_id`` field, to ensure the ``_id``
is set correctly via associations:

.. code-block:: ruby

  field :_id, type: String, default: -> { 'hello' }, 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:

Field Aliases
-------------

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 :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``
`````````````````

``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">


Reserved Names
--------------

Attempting to define a field on a document that conflicts with a reserved
method name in Mongoid will raise an error. The list of reserved names can
be obtained by invoking the ``Mongoid.destructive_fields`` method.


Field Redefinition
------------------

By default Mongoid allows redefining fields on a model. To raise an error
when a field is redefined, set the ``duplicate_fields_exception``
:ref:`configuration option <configuration-options>` to ``true``.

With the option set to true, the following example will raise an error:

.. code-block:: ruby

  class Person
    include Mongoid::Document

    field :name

    field :name, type: String
  end

To define the field anyway, use the ``overwrite: true`` option:

.. code-block:: ruby

  class Person
    include Mongoid::Document

    field :name

    field :name, type: String, overwrite: true
  end


.. _custom-id:

Custom IDs
----------

By default, Mongoid defines the ``_id`` field on documents to contain a
``BSON::ObjectId`` 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

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. In this case, if the document is a top-level document, an ``_id``
value will be assigned by the server; if the document is an embedded document,
no ``_id`` value will be assigned. Mongoid will not automatically retrieve
this value, if assigned, 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``.

.. _uncastable-values:

Uncastable Values
-----------------

In Mongoid 8, Mongoid has standardized the treatment of the assignment and
reading of "uncastable" values. A value is considered "uncastable" when it
cannot be coerced to the type of its field. For example, an array would be an
"uncastable" value to an Integer field.


Assigning Uncastable Values
```````````````````````````

The assignment of uncastable values has been standardized to assign ``nil`` by
default. Consider the following example:

.. code::

  class User
    include Mongoid::Document

    field :name, type: Integer
  end

  User.new(name: [ "hello" ])

Assigning an array to a field of type Integer doesn't work since an array can't
be coerced to an Integer. The assignment of uncastable values to a field will
cause a ``nil`` to be written:

.. code::

  user = User.new(name: [ "Mike", "Trout" ])
  # => #<User _id: 62b222d43282a47bf73e3264, name: nil>

Note that the original uncastable values will be stored in the
``attributes_before_type_cast`` hash with their field names:

.. code::

  user.attributes_before_type_cast["name"]
  # => ["Mike", "Trout"]

.. note::

  Note that for numeric fields, any class that defines ``to_i`` for Integer
  fields, ``to_f`` for Floats, and ``to_d`` for BigDecimals, is castable.
  Strings are the exception and will only call the corresponding ``to_*``
  method if the string is numeric. If a class only defines ``to_i`` and not
  ``to_f`` and is being assigned to a Float field, this is uncastable, and Mongoid
  will not perform a two-step conversion (i.e. ``to_i`` and then ``to_f``).


Reading Uncastable Values
`````````````````````````

When documents in the database contain values of different types than their
represenations in Mongoid, if Mongoid cannot coerce them into the correct type,
it will replace the value with ``nil``. Consider the following model and document in the
database:

.. code::

  class User
    include Mongoid::Document

    field :name, type: Integer
  end

.. code::

  { _id: ..., name: [ "Mike", "Trout" ] }

Reading this document from the database will result in the model's name field
containing ``nil``:

.. code::

  User.first.name
  # => nil

The database value of type array cannot be stored in the attribute, since the
array can't be coerced to an Integer. Note that the original uncastable values
will be stored in the ``attributes_before_type_cast`` hash with their field
names:

.. code::

  user.attributes_before_type_cast["name"]
  # => ["Mike", "Trout"]

.. note::

  The ``demongoize`` methods on container objects (i.e. Hash, Array) have not
  been changed to permit automatic persistence of mutated container attributes.
  See `MONGOID-2951 <https://jira.mongodb.org/browse/MONGOID-2951>`_ for a
  longer discussion of this topic.


.. _customizing-field-behavior:

Customizing Field Behavior
==========================

Mongoid offers several ways to customize the behavior of fields.


.. _custom-getters-and-setters:

Custom Getters And Setters
--------------------------

You may override getters and setters for fields to modify the values
when they are being accessed or written. The getters and setters use the
same name as the field. Use ``read_attribute`` and ``write_attribute``
methods inside the getters and setters to operate on the raw attribute
values.

For example, Mongoid provides the ``:default`` field option to write a
default value into the field. If you wish to have a field default value
in your application but do not wish to persist it, you can override the
getter as follows:

.. code-block:: ruby

  class DistanceMeasurement
    include Mongoid::Document

    field :value, type: Float
    field :unit, type: String

    def unit
      read_attribute(:unit) || "m"
    end

    def to_s
      "#{value} #{unit}"
    end
  end

  measurement = DistanceMeasurement.new(value: 2)
  measurement.to_s
  # => "2.0 m"
  measurement.attributes
  # => {"_id"=>BSON::ObjectId('613fa0b0a15d5d61502f3447'), "value"=>2.0}

To give another example, a field which converts empty strings to nil values
may be implemented as follows:

.. code-block:: ruby

  class DistanceMeasurement
    include Mongoid::Document

    field :value, type: Float
    field :unit, type: String

    def unit=(value)
      if value.blank?
        value = nil
      end
      write_attribute(:unit, value)
    end
  end

  measurement = DistanceMeasurement.new(value: 2, unit: "")
  measurement.attributes
  # => {"_id"=>BSON::ObjectId('613fa15aa15d5d617216104c'), "value"=>2.0, "unit"=>nil}


.. _custom-field-types:

Custom Field Types
------------------

You can define custom types in Mongoid and determine how they are serialized
and deserialized. In this example, we define a new field type ``Point``, which we
can use in our model class as follows:

.. code-block:: ruby

  class Profile
    include Mongoid::Document
    field :location, type: Point
  end

Then make a Ruby class to represent the type. This class must define methods
used for MongoDB serialization and deserialization as follows:

.. code-block:: ruby

  class Point

    attr_reader :x, :y

    def initialize(x, y)
      @x, @y = x, y
    end

    # Converts an object of this instance into a database friendly value.
    # In this example, we store the values in the database as array.
    def mongoize
      [ x, y ]
    end

    class << self

      # Takes any possible object and converts it to how it would be
      # stored in the database.
      def mongoize(object)
        case object
        when Point then object.mongoize
        when Hash then Point.new(object[:x], object[:y]).mongoize
        else object
        end
      end

      # Get the object as it was stored in the database, and instantiate
      # this custom class from it.
      def demongoize(object)
        Point.new(object[0], object[1])
      end

      # Converts the object that was supplied to a criteria and converts it
      # into a query-friendly form.
      def evolve(object)
        case object
        when Point then object.mongoize
        else object
        end
      end
    end
  end

The instance method ``mongoize`` takes an instance of your custom type object, and
converts it into a represenation of how it will be stored in the database, i.e. to pass
to the MongoDB Ruby driver. In our example above, we want to store our ``Point``
object as an ``Array`` in the form ``[ x, y ]``.

The class method ``mongoize`` is similar to the instance method, however it must handle
objects of all possible types as inputs. The ``mongoize`` method is used when calling the
setter methods for fields of your custom type.

.. code-block:: ruby

   point = Point.new(12, 24)
   venue = Venue.new(location: point) # This uses the Point#mongoize instance method.
   venue = Venue.new(location: [ 12, 24 ]) # This uses the Point.mongoize class method.

The class method ``demongoize`` does the inverse of ``mongoize``. It takes the raw object
from the MongoDB Ruby driver and converts it to an instance of your custom type.
In this case, the database driver returns an ``Array`` and we instantiate a ``Point`` from it.
The ``demongoize`` method is used when calling the getters of fields for your custom type.
Note that in the example above, since ``demongoize`` calls ``Point.new``, a new instance of
``Point`` will be generated on each call to the getter.

Mongoid will always call the ``demongoize`` method on values that were
retrieved from the database, but applications may, in theory, call
``demongoize`` with arbitrary input. It is recommended that applications add
handling for arbitrary input in their ``demongoize`` methods. We can rewrite
``Point``'s demongoize method as follows:

.. code:: ruby

  def demongoize(object)
    if object.is_a?(Array) && object.length == 2
      Point.new(object[0], object[1])
    end
  end

Notice that ``demongoize`` will only create a new ``Point`` if given an array
of length 2, and will return ``nil`` otherwise. Both the ``mongoize`` and
``demongoize`` methods should be prepared to receive arbitrary input and should
return ``nil`` on values that are uncastable to your custom type. See the
section on :ref:`Uncastable Values <uncastable-values>` for more details.

Lastly, the class method ``evolve`` is similar to ``mongoize``, however it is used
when transforming objects for use in Mongoid query criteria.

.. code-block:: ruby

   point = Point.new(12, 24)
   Venue.where(location: point) # This uses Point.evolve

The ``evolve`` method should also be prepared to receive arbitrary input,
however, unlike the ``mongoize`` and ``demongoize`` methods, it should return
the inputted value on values that are uncastable to your custom type. See the
section on :ref:`Uncastable Values <uncastable-values>` for more details.


.. _phantom-custom-field-types:

Phantom Custom Field Types
``````````````````````````

The custom field type may perform conversions from user-visible attribute
values to the values stored in the database when the user-visible attribute
value type is different from the declared field type. For example, this
can be used to implement a mapping from one enumeration to another, to
have more descriptive values in the application and more compact values stored
in the database:

.. code-block:: ruby

  class ColorMapping

    MAPPING = {
      'black' => 0,
      'white' => 1,
    }.freeze

    INVERSE_MAPPING = MAPPING.invert.freeze

    class << self

      # Takes application-scope value and converts it to how it would be
      # stored in the database. Converts invalid values to nil.
      def mongoize(object)
        MAPPING[object]
      end

      # Get the value as it was stored in the database, and convert to
      # application-scope value. Converts invalid values to nil.
      def demongoize(object)
        INVERSE_MAPPING[object]
      end

      # Converts the object that was supplied to a criteria and converts it
      # into a query-friendly form. Returns invalid values as is.
      def evolve(object)
        MAPPING.fetch(object, object)
      end
    end
  end

  class Profile
    include Mongoid::Document
    field :color, type: ColorMapping
  end

  profile = Profile.new(color: 'white')
  profile.color
  # => "white"

  # Writes 0 to color field
  profile.save!


.. _custom-field-options:

Custom Field Options
--------------------

You may define custom options for the ``field`` macro function
which extend its behavior at the your time model classes are loaded.

As an example, we will define a ``:max_length`` option which will add a length
validator for the field. First, declare the new field option in an initializer,
specifiying its handler function as a block:

.. code-block:: ruby

  # in /config/initializers/mongoid_custom_fields.rb

  Mongoid::Fields.option :max_length do |model, field, value|
    model.validates_length_of field.name, maximum: value
  end

Then, use it your model class:

.. code-block:: ruby

  class Person
    include Mongoid::Document

    field :name, type: String, max_length: 10
  end

Note that the handler function will be invoked whenever the option is used
in the field definition, even if the option's value is false or nil.


.. _dynamic-fields:

Dynamic Fields
==============

By default, Mongoid requires all fields that may be set on a document to
be explicitly defined using ``field`` declarations. Mongoid also supports
creating fields on the fly from an arbitrary hash or documents stored in
the database. When a model uses fields not explicitly defined, such fields
are called *dynamic fields*.

To enable dynamic fields, include ``Mongoid::Attributes::Dynamic`` module
in the model:

.. code-block:: ruby

  class Person
    include Mongoid::Document
    include Mongoid::Attributes::Dynamic
  end

  bob = Person.new(name: 'Bob', age: 42)
  bob.name
  # => "Bob"

It is possible to use ``field`` declarations and dynamic fields in the same
model class. Attributes for which there is a ``field`` declaration will be
treated according to the ``field`` declaration, with remaining attributes
being treated as dynamic fields.

Attribute values in the dynamic fields must initially be set by either
passing the attribute hash to the constructor, mass assignment via
``attributes=``, mass assignment via ``[]=``, using ``write_attribute``,
or they must already be present in the database.

.. code-block:: ruby

  # OK
  bob = Person.new(name: 'Bob')

  # OK
  bob = Person.new
  bob.attributes = {age: 42}

  # OK
  bob = Person.new
  bob['age'] = 42

  # Raises NoMethodError: undefined method age=
  bob = Person.new
  bob.age = 42

  # OK
  bob = Person.new
  # OK - string access
  bob.write_attribute('age', 42)
  # OK - symbol access
  bob.write_attribute(:name, 'Bob')

  # OK, initializes attributes from whatever is in the database
  bob = Person.find('123')

If an attribute is not present in a particular model instance's attributes
hash, both the reader and the writer for the corresponding field are not
defined, and invoking them raises ``NoMethodError``:

.. code-block:: ruby

  bob = Person.new
  bob.attributes = {age: 42}

  bob.age
  # => 42

  # raises NoMethodError
  bob.name

  # raises NoMethodError
  bob.name = 'Bob'

  # OK
  bob['name'] = 'Bob'

  bob.name
  # => "Bob"

Attributes can always be read using mass attribute access or ``read_attribute``
(this applies to models not using dynamic fields as well):

.. code-block:: ruby

  bob = Person.new(age: 42)

  # OK - string access
  bob['name']
  # => nil

  # OK - symbol access
  bob[:name]
  # => nil

  # OK - string access
  bob['age']
  # => 42

  # OK - symbol access
  bob[:age]
  # => 42

  # OK
  bob.attributes['name']
  # => nil

  # OK
  bob.attributes['age']
  # => 42

  # Returns nil - keys are always strings
  bob.attributes[:age]
  # => nil

  # OK
  bob.read_attribute('name')
  # => nil

  # OK
  bob.read_attribute(:name)
  # => nil

  # OK - string access
  bob.read_attribute('age')
  # => 42

  # OK - symbol access
  bob.read_attribute(:age)
  # => 42

.. note::

  The values returned from the ``read_attribute`` method, and those stored in
  the ``attributes`` hash, are the ``mongoized`` values.


Special Characters in Field Names
---------------------------------

Mongoid permits dynamic field names to include spaces and punctuation:

.. code-block:: ruby

  bob = Person.new('hello world' => 'MDB')
  bob.send('hello world')
  # => "MDB"

  bob.write_attribute("hello%world", 'MDB')
  bob[:"hello%world"]
  # => "MDB"


Localized Fields
================

Mongoid supports localized fields via `i18n <https://github.com/ruby-i18n/i18n>`_.

.. code-block:: ruby

   class Product
     include Mongoid::Document
     field :description, type: String, localize: true
   end

By telling the field to ``localize``, Mongoid will under the covers store the field
as a hash of locale/value pairs, but normal access to it will behave like a string.

.. code-block:: ruby

   I18n.default_locale = :en
   product = Product.new
   product.description = "Marvelous!"
   I18n.locale = :de
   product.description = "Fantastisch!"

   product.attributes
   # { "description" => { "en" => "Marvelous!", "de" => "Fantastisch!" }

You can get and set all the translations at once by using the corresponding ``_translations`` method.

.. code-block:: ruby

   product.description_translations
   # { "en" => "Marvelous!", "de" => "Fantastisch!" }
   product.description_translations =
     { "en" => "Marvelous!", "de" => "Wunderbar!" }

Localized fields can be used with any field type. For example, they can be used
with float fields for differences with currency:

.. code:: ruby

  class Product
    include Mongoid::Document

    field :price, type: Float, localize: true
    field :currency, type: String, localize: true
  end

By creating the model in this way, we can separate the price from the currency
type, which allows you to use all of the number-related functionalities on the
price when querying or aggregating that field (provided that you index into the
stored translations hash). We can create an instance of this model as follows:

.. code:: ruby

  product = Product.new
  I18n.locale = :en
  product.price = 1.00
  product.currency = "$"
  I18n.locale = :he
  product.price = 3.24
  product.currency = "₪"

  product.attributes
  # => { "price" => { "en" => 1.0, "he" => 3.24 }, "currency" => { "en" => "$", "he" => "₪"  } }


.. _present-fields:

Localize ``:present`` Field Option
----------------------------------

Mongoid supports the ``:present`` option when creating a localized field:

.. code-block:: ruby

   class Product
     include Mongoid::Document
     field :description, localize: :present
   end

This option automatically removes ``blank`` values (i.e. those that return true
for the ``blank?`` method) from the ``_translations`` hash:

.. code-block:: ruby

   I18n.default_locale = :en
   product = Product.new
   product.description = "Marvelous!"
   I18n.locale = :de
   product.description = "Fantastisch!"

   product.description_translations
   # { "en" => "Marvelous!", "de" => "Fantastisch!" }

   product.description = ""
   product.description_translations
   # { "en" => "Marvelous!" }

When the empty string is written for the ``:de`` locale, the ``"de"`` key is
removed from the ``_translations`` hash instead of writing the empty string.


Fallbacks
---------

Mongoid integrates with
`i18n fallbacks <https://github.com/ruby-i18n/i18n/wiki/Fallbacks>`_.
To use the fallbacks, the respective functionality must be explicitly enabled.

In a Rails application, set the ``config.i18n.fallbacks`` configuration setting
to ``true`` in your environment and specify the fallback languages:

.. code-block:: ruby

  config.i18n.fallbacks = true
  config.after_initialize do
    I18n.fallbacks[:de] = [ :en, :es ]
  end

In a non-Rails application, include the fallbacks module into the I18n backend
you are using and specify the fallback languages:

.. code-block:: ruby

  require "i18n/backend/fallbacks"
  I18n::Backend::Simple.send(:include, I18n::Backend::Fallbacks)
  I18n.fallbacks[:de] = [ :en, :es ]

When fallbacks are enabled, if a translation is not present in the active
language, translations will be looked up in the fallback languages:

.. code-block:: ruby

  product = Product.new
  I18n.locale = :en
  product.description = "Marvelous!"
  I18n.locale = :de
  product.description # "Marvelous!"

Mongoid also defines a ``:fallbacks`` option on fields, which can be used to
disable fallback functionality on a specific field:

.. code:: ruby

  class Product
    include Mongoid::Document
    field :description, type: String, localize: true, fallbacks: false
  end

  product = Product.new
  I18n.locale = :en
  product.description = "Marvelous!"
  I18n.locale = :de
  product.description # nil

Note that this option defaults to ``true``.

.. note::

  In i18n 1.1, the behavior of fallbacks `changed <https://github.com/ruby-i18n/i18n/pull/415>`_
  to always require an explicit list of fallback locales rather than falling
  back to the default locale when no fallback locales have been provided.


Querying
--------

When querying for localized fields using Mongoid's criteria API, Mongoid will automatically
alter the criteria to match the current locale.

.. code-block:: ruby

   # Match all products with Marvelous as the description. Locale is en.
   Product.where(description: "Marvelous!")
   # The resulting MongoDB query filter: { "description.en" : "Marvelous!" }


Indexing
--------

If you plan to be querying extensively on localized fields, you should index each of the
locales that you plan on searching on.

.. code-block:: ruby

   class Product
     include Mongoid::Document
     field :description, localize: true

     index "description.de" => 1
     index "description.en" => 1
   end


.. _read-only:

Read-Only Attributes
====================

You can tell Mongoid that certain attributes are read-only. This will allow
documents to be created with these attributes, but changes to them will be
ignored when using mass update methods such as ``update_attributes``:

.. code-block:: ruby

   class Band
     include Mongoid::Document
     field :name, type: String
     field :origin, type: String

     attr_readonly :name, :origin
   end

   band = Band.create(name: "Placebo")
   band.update_attributes(name: "Tool") # Filters out the name change.

If you explicitly try to update or remove a read-only attribute by itself,
a ``ReadonlyAttribute`` exception will be raised:

.. code-block:: ruby

   band.update_attribute(:name, "Tool") # Raises the error.
   band.remove_attribute(:name) # Raises the error.

Assignments to read-only attributes using their setters will be ignored:

.. code-block:: ruby

  b = Band.create!(name: "The Rolling Stones")
  # => #<Band _id: 6287a3d5d1327a5292535383, name: "The Rolling Stones", origin: nil>
  b.name = "The Smashing Pumpkins"
  # => "The Smashing Pumpkins"
  b.name
  # => "The Rolling Stones"

Calls to atomic persistence operators, like ``bit`` and ``inc``, will persist
changes to readonly fields.

Timestamp Fields
================

Mongoid supplies a timestamping module in ``Mongoid::Timestamps`` which
can be included to get basic behavior for ``created_at`` and
``updated_at`` fields.

.. code-block:: ruby

   class Person
     include Mongoid::Document
     include Mongoid::Timestamps
   end

You may also choose to only have specific timestamps for creation or
modification.

.. code-block:: ruby

   class Person
     include Mongoid::Document
     include Mongoid::Timestamps::Created
   end

   class Post
     include Mongoid::Document
     include Mongoid::Timestamps::Updated
   end

If you want to turn off timestamping for specific calls, use the timeless
method:

.. code-block:: ruby

   person.timeless.save
   Person.timeless.create!

If you'd like shorter timestamp fields with aliases on them to save space,
you can include the short versions of the modules.

.. code-block:: ruby

   class Band
     include Mongoid::Document
     include Mongoid::Timestamps::Short # For c_at and u_at.
   end

   class Band
     include Mongoid::Document
     include Mongoid::Timestamps::Created::Short # For c_at only.
   end

   class Band
     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 (``$``)
==============================================================

Using dots/periods (``.``) in fields names and starting a field name with
a dollar sign (``$``) is not recommended, as Mongoid provides limited support
for retrieving and operating on the documents stored in those fields.

Both Mongoid and MongoDB query language (MQL) generally use the dot/period
character (``.``) to separate field names in a field path that traverses
embedded documents, and words beginning with the dollar sign (``$``) as
operators. MongoDB provides `limited support
<https://www.mongodb.com/docs/manual/core/dot-dollar-considerations/#std-label-crud-concepts-dot-dollar-considerations>`_
for using field names containing dots and starting with the dollar sign
for interoperability with other software,
however, due to this support being confined to specific operators
(e.g. :manual:`getField </reference/operator/aggregation/getField/>`,
:manual:`setField </reference/operator/aggregation/setField/>`) and
requiring the usage of the aggregation pipeline for both queries and updates,
applications should avoid using dots in field names and starting field names
with the dollar sign if possible.

Mongoid, starting in version 8, now allows users to access fields that begin with
dollar signs and that contain dots/periods. They can be accessed using the ``send``
method as follows:

.. code::

    class User
      include Mongoid::Document
      field :"first.last", type: String
      field :"$_amount", type: Integer
    end

    user = User.first
    user.send(:"first.last")
    # => Mike.Trout
    user.send(:"$_amount")
    # => 42650000

It is also possible to use ``read_attribute`` to access these fields:

.. code::

    user.read_attribute("first.last")
    # => Mike.Trout

Due to `server limitations <https://www.mongodb.com/docs/manual/core/dot-dollar-considerations/>`_,
updating and replacing fields containing dots and dollars requires using special
operators. For this reason, calling setters on these fields is prohibited and
will raise an error:

.. code::

    class User
      include Mongoid::Document
      field :"first.last", type: String
      field :"$_amount", type: Integer
    end

    user = User.new
    user.send(:"first.last=", "Shohei.Ohtani")
    # raises a InvalidDotDollarAssignment error
    user.send(:"$_amount=", 8500000)
    # raises a InvalidDotDollarAssignment error