module Mongoid::Document

This is the base module for all domain objects that need to be persisted to the database as documents.

Constants

ILLEGAL_KEY

Regex for matching illegal BSON keys. Note that bson 4.1 has the constant BSON::String::ILLEGAL_KEY that should be used instead. When ruby driver 2.3.0 is released and Mongoid can be updated to require >= 2.3.0, the BSON constant can be used.

@since 6.0.0

Attributes

__selected_fields[RW]
new_record[R]

Public Class Methods

new(attrs = nil) { |self| ... } click to toggle source

Instantiate a new Document, setting the Document’s attributes if given. If no attributes are provided, they will be initialized with an empty Hash.

If a primary key is defined, the document’s id will be set to that key, otherwise it will be set to a fresh BSON::ObjectId string.

@example Create a new document.

Person.new(:title => "Sir")

@param [ Hash ] attrs The attributes to set up the document with.

@return [ Document ] A new document.

@since 1.0.0

# File lib/mongoid/document.rb, line 116
def initialize(attrs = nil)
  @__parent = nil
  _building do
    @new_record = true
    @attributes ||= {}
    apply_pre_processed_defaults
    apply_default_scoping
    process_attributes(attrs) do
      yield(self) if block_given?
    end
    apply_post_processed_defaults
    # @todo: #2586: Need to have access to parent document in these
    #   callbacks.
    run_callbacks(:initialize) unless _initialize_callbacks.empty?
  end
end

Public Instance Methods

as_document() click to toggle source

Return a hash of the entire document hierarchy from this document and below. Used when the attributes are needed for everything and not just the current document.

@example Get the full hierarchy.

person.as_document

@return [ Hash ] A hash of all attributes in the hierarchy.

@since 1.0.0

# File lib/mongoid/document.rb, line 179
def as_document
  BSON::Document.new(as_attributes)
end
as_json(options = nil) click to toggle source

Calls as_json on the document with additional, Mongoid-specific options.

@note Rails 6 changes return value of as_json for non-primitive types

such as BSON::ObjectId. In Rails <= 5, as_json returned these as
instances of the class. In Rails 6, these are returned serialized to
primitive types (e.g. {"$oid"=>"5bcfc40bde340b37feda98e9"}).
See https://github.com/rails/rails/commit/2e5cb980a448e7f4ab00df6e9ad4c1cc456616aa
for more information.

@example Get the document as json.

document.as_json(compact: true)

@param [ Hash ] options The options.

@option options [ true, false ] :compact (Deprecated) Whether to include fields

with nil values in the json document.

@return [ Hash ] The document as json.

@since 5.1.0

Calls superclass method
# File lib/mongoid/document.rb, line 203
def as_json(options = nil)
  rv = super
  if options && options[:compact]
    Mongoid.logger.warn('#as_json :compact option is deprecated. Please call #compact on the returned Hash object instead.')
    rv = rv.compact
  end
  rv
end
becomes(klass) click to toggle source

Returns an instance of the specified class with the attributes, errors, and embedded documents of the current document.

@example Return a subclass document as a superclass instance.

manager.becomes(Person)

@raise [ ArgumentError ] If the class doesn’t include Mongoid::Document

@param [ Class ] klass The class to become.

@return [ Document ] An instance of the specified class.

@since 2.0.0

# File lib/mongoid/document.rb, line 225
def becomes(klass)
  unless klass.include?(Mongoid::Document)
    raise ArgumentError, "A class which includes Mongoid::Document is expected"
  end

  became = klass.new(clone_document)
  became._id = _id
  became.instance_variable_set(:@changed_attributes, changed_attributes)
  new_errors = ActiveModel::Errors.new(became)
  new_errors.copy!(errors)
  became.instance_variable_set(:@errors, new_errors)
  became.instance_variable_set(:@new_record, new_record?)
  became.instance_variable_set(:@destroyed, destroyed?)
  became.changed_attributes[klass.discriminator_key] = self.class.discriminator_value
  became[klass.discriminator_key] = klass.discriminator_value

  # mark embedded docs as persisted
  embedded_relations.each_pair do |name, meta|
    without_autobuild do
      relation = became.__send__(name)
      Array.wrap(relation).each do |r|
        r.instance_variable_set(:@new_record, new_record?)
      end
    end
  end

  became
end
freeze() click to toggle source

Freezes the internal attributes of the document.

@example Freeze the document

document.freeze

@return [ Document ] The document.

@since 2.0.0

# File lib/mongoid/document.rb, line 55
def freeze
  as_attributes.freeze and self
end
frozen?() click to toggle source

Checks if the document is frozen

@example Check if frozen

document.frozen?

@return [ true, false ] True if frozen, else false.

@since 2.0.0

# File lib/mongoid/document.rb, line 67
def frozen?
  attributes.frozen?
end
hash() click to toggle source

Delegates to identity in order to allow two records of the same identity to work with something like:

[ Person.find(1), Person.find(2), Person.find(3) ] &
[ Person.find(1), Person.find(4) ] # => [ Person.find(1) ]

@example Get the hash.

document.hash

@return [ Integer ] The hash of the document’s identity.

@since 1.0.0

# File lib/mongoid/document.rb, line 83
def hash
  identity.hash
end
identity() click to toggle source

A Document’s is identified absolutely by its class and database id:

Person.first.identity #=> [Person, BSON::ObjectId(‘4f775130a04745933a000003’)]

@example Get the identity

document.identity

@return [ Array ] An array containing [document.class, document._id]

@since 3.0.0

# File lib/mongoid/document.rb, line 97
def identity
  [ self.class, self._id ]
end
model_name() click to toggle source

Return the model name of the document.

@example Return the model name.

document.model_name

@return [ String ] The model name.

@since 3.0.16

# File lib/mongoid/document.rb, line 141
def model_name
  self.class.model_name
end
to_a() click to toggle source

Return an array with this Document only in it.

@example Return the document in an array.

document.to_a

@return [ Array<Document> ] An array with the document as its only item.

@since 1.0.0

# File lib/mongoid/document.rb, line 165
def to_a
  [ self ]
end
to_key() click to toggle source

Return the key value for the document.

@example Return the key.

document.to_key

@return [ String ] The id of the document or nil if new.

@since 2.4.0

# File lib/mongoid/document.rb, line 153
def to_key
  (persisted? || destroyed?) ? [ _id.to_s ] : nil
end

Private Instance Methods

as_attributes() click to toggle source
# File lib/mongoid/document.rb, line 277
def as_attributes
  return attributes if frozen?
  embedded_relations.each_pair do |name, meta|
    without_autobuild do
      relation, stored = send(name), meta.store_as
      if attributes.key?(stored) || !relation.blank?
        if !relation.nil?
          attributes[stored] = relation.send(:as_attributes)
        else
          attributes.delete(stored)
        end
      end
    end
  end
  attributes
end
logger() click to toggle source

Returns the logger

@return [ Logger ] The configured logger or a default Logger instance.

@since 2.2.0

# File lib/mongoid/document.rb, line 261
def logger
  Mongoid.logger
end
model_key() click to toggle source

Get the name of the model used in caching.

@example Get the model key.

model.model_key

@return [ String ] The model key.

@since 2.4.0

# File lib/mongoid/document.rb, line 273
def model_key
  @model_cache_key ||= self.class.model_name.cache_key
end