Module: Mongoid::Document

Extended by:
ActiveSupport::Concern
Includes:
Composable, Touchable::InstanceMethods
Included in:
GlobalDiscriminatorKeyAssignment::InvalidFieldHost
Defined in:
lib/mongoid/document.rb

Overview

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

Defined Under Namespace

Modules: ClassMethods

Constant Summary collapse

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.

/(\A[$])|(\.)/.freeze

Constants included from Composable

Composable::MODULES, Composable::RESERVED_METHOD_NAMES

Constants included from Interceptable

Interceptable::CALLBACKS

Constants included from Association

Association::MACRO_MAPPING

Constants included from Association::Depending

Association::Depending::STRATEGIES

Constants included from Persistable

Persistable::LIST_OPERATIONS

Constants included from Fields

Fields::Boolean, Fields::IDS, Fields::StringifiedSymbol, Fields::TYPE_MAPPINGS

Constants included from Atomic

Atomic::UPDATES

Instance Attribute Summary collapse

Attributes included from Stateful

#destroyed, #flagged_for_destroy

Attributes included from Association

#_association

Attributes included from Attributes

#attributes

Instance Method Summary collapse

Methods included from Touchable::InstanceMethods

#touch

Methods included from Composable

prohibited_methods

Methods included from Equality

#<=>, #==, #===, #eql?

Methods included from Copyable

#clone

Methods included from Interceptable

#callback_executable?, #in_callback_state?, #run_after_callbacks, #run_before_callbacks, #run_callbacks

Methods included from Validatable

#begin_validate, #exit_validate, #performing_validations?, #read_attribute_for_validation, #valid?, #validated?, #validating_with_query?

Methods included from Traversable

#_children, #_descendants, #_parent, #_parent=, #_reset_memoized_descendants!, #_root, #_root?, #collect_children, #collect_descendants, #flag_descendants_persisted, #hereditary?, #parentize, #remove_child, #reset_persisted_descendants

Methods included from Cacheable

#cache_key

Methods included from Stateful

#destroyed?, #flagged_for_destroy?, #new_record?, #persisted?, #pushable?, #readonly?, #settable?, #updateable?

Methods included from Shardable

#shard_key_fields, #shard_key_selector, #shard_key_selector_in_db

Methods included from Serializable

#serializable_hash

Methods included from Selectable

#atomic_selector

Methods included from Reloadable

#reload

Methods included from Association

#association_name, #embedded?, #embedded_many?, #embedded_one?, #referenced_many?, #referenced_one?, #reload_relations

Methods included from Association::Reflections

#reflect_on_all_association, #reflect_on_association

Methods included from Association::Macros

#associations

Methods included from Association::Depending

#apply_destroy_dependencies!, define_dependency!, validate!

Methods included from Association::Accessors

#__build__, #create_relation, #reset_relation_criteria, #set_relation

Methods included from Association::Referenced::Syncable

#_syncable?, #_synced, #_synced?, #remove_inverse_keys, #update_inverse_keys

Methods included from Association::Referenced::CounterCache

define_callbacks!, #reset_counters

Methods included from Association::Referenced::AutoSave

#__autosaving__, #autosaved?, #changed_for_autosave?, define_autosave!

Methods included from Persistable

#atomically, #fail_due_to_callback!, #fail_due_to_validation!

Methods included from Persistable::Unsettable

#unset

Methods included from Persistable::Upsertable

#upsert

Methods included from Persistable::Updatable

#update, #update!, #update_attribute

Methods included from Persistable::Settable

#set

Methods included from Persistable::Savable

#save, #save!

Methods included from Persistable::Renamable

#rename

Methods included from Persistable::Pushable

#add_to_set, #push

Methods included from Persistable::Pullable

#pull, #pull_all

Methods included from Positional

#positionally

Methods included from Persistable::Poppable

#pop

Methods included from Persistable::Logical

#bit

Methods included from Persistable::Incrementable

#inc

Methods included from Persistable::Destroyable

#destroy, #destroy!

Methods included from Persistable::Deletable

#delete

Methods included from Persistable::Creatable

#insert

Methods included from Matchable

#_matches?

Methods included from Inspectable

#inspect

Methods included from Fields

#apply_default, #apply_defaults, #apply_post_processed_defaults, #apply_pre_processed_defaults, #attribute_names, #database_field_name, #lazy_settable?, option, options, #using_object_ids?

Methods included from Evolvable

#__evolve_object_id__

Methods included from Attributes

#assign_attributes, #attribute_missing?, #attribute_present?, #attributes_before_type_cast, #has_attribute?, #has_attribute_before_type_cast?, #read_attribute, #read_attribute_before_type_cast, #remove_attribute, #typed_attributes, #write_attribute, #write_attributes

Methods included from Attributes::Readonly

#attribute_writable?

Methods included from Attributes::Processing

#process_attributes

Methods included from Clients

clear, clients, default, disconnect, set, with_name

Methods included from Clients::Sessions

#with_session

Methods included from Clients::Options

#collection, #collection_name, #mongo_client, #persistence_context, #with

Methods included from Changeable

#changed, #changed?, #changed_attributes, #changes, #children_changed?, #move_changes, #post_persist, #previous_changes, #remove_change, #setters

Methods included from Atomic

#add_atomic_pull, #add_atomic_unset, #atomic_array_add_to_sets, #atomic_array_pulls, #atomic_array_pushes, #atomic_attribute_name, #atomic_delete_modifier, #atomic_insert_modifier, #atomic_path, #atomic_paths, #atomic_position, #atomic_pulls, #atomic_pushes, #atomic_sets, #atomic_unsets, #atomic_updates, #delayed_atomic_pulls, #delayed_atomic_sets, #delayed_atomic_unsets, #flag_as_destroyed, #flagged_destroys, #process_flagged_destroys

Instance Attribute Details

#__selected_fields ⇒ Object

Returns the value of attribute __selected_fields.



30
31
32
 
# File 'lib/mongoid/document.rb', line 30

def __selected_fields
  @__selected_fields
end

#new_record ⇒ Object (readonly)

Returns the value of attribute new_record.



31
32
33
 
# File 'lib/mongoid/document.rb', line 31

def new_record
  @new_record
end

Instance Method Details

#as_document ⇒ Hash

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.

Examples:

Get the full hierarchy.

person.as_document

Returns:

  • (Hash) —

    A hash of all attributes in the hierarchy.



158
159
160
 
# File 'lib/mongoid/document.rb', line 158

def as_document
  BSON::Document.new(as_attributes)
end

#as_json(options = nil) ⇒ Hash

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 github.com/rails/rails/commit/2e5cb980a448e7f4ab00df6e9ad4c1cc456616aa for more information.

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

Examples:

Get the document as json.

document.as_json(compact: true)

Parameters:

  • options (Hash) (defaults to: nil) —

    The options.

Options Hash (options):

  • :compact (true, false) — default: Deprecated —

    Whether to include fields with nil values in the json document.

Returns:

  • (Hash) —

    The document as json.



180
181
182
183
184
185
186
187
 
# File 'lib/mongoid/document.rb', line 180

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) ⇒ Document

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

Examples:

Return a subclass document as a superclass instance.

manager.becomes(Person)

Parameters:

  • klass (Class) —

    The class to become.

Returns:

  • (Document) —

    An instance of the specified class.

Raises:

  • (ArgumentError) —

    If the class doesn’t include Mongoid::Document



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/mongoid/document.rb', line 200

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 ⇒ Document

Freezes the internal attributes of the document.

Examples:

Freeze the document

document.freeze

Returns:



50
51
52
 
# File 'lib/mongoid/document.rb', line 50

def freeze
  as_attributes.freeze and self
end

#frozen? ⇒ true, false

Checks if the document is frozen

Examples:

Check if frozen

document.frozen?

Returns:

  • (true, false) —

    True if frozen, else false.



60
61
62
 
# File 'lib/mongoid/document.rb', line 60

def frozen?
  attributes.frozen?
end

#hash ⇒ Integer

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) ]

Examples:

Get the hash.

document.hash

Returns:

  • (Integer) —

    The hash of the document’s identity.



74
75
76
 
# File 'lib/mongoid/document.rb', line 74

def hash
  identity.hash
end

#identity ⇒ Array

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

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

Examples:

Get the identity

document.identity

Returns:

  • (Array) —

    An array containing [document.class, document._id]



86
87
88
 
# File 'lib/mongoid/document.rb', line 86

def identity
  [ self.class, self._id ]
end

#initialize(attrs = nil) ⇒ Document

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.

Examples:

Create a new document.

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

Parameters:

  • attrs (Hash) (defaults to: nil) —

    The attributes to set up the document with.

Returns:



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/mongoid/document.rb', line 103

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

#model_name ⇒ String

Return the model name of the document.

Examples:

Return the model name.

document.model_name

Returns:

  • (String) —

    The model name.



126
127
128
 
# File 'lib/mongoid/document.rb', line 126

def model_name
  self.class.model_name
end

#to_a ⇒ Array<Document>

Return an array with this Document only in it.

Examples:

Return the document in an array.

document.to_a

Returns:

  • (Array<Document>) —

    An array with the document as its only item.



146
147
148
 
# File 'lib/mongoid/document.rb', line 146

def to_a
  [ self ]
end

#to_key ⇒ String

Return the key value for the document.

Examples:

Return the key.

document.to_key

Returns:

  • (String) —

    The id of the document or nil if new.



136
137
138
 
# File 'lib/mongoid/document.rb', line 136

def to_key
  (persisted? || destroyed?) ? [ _id.to_s ] : nil
end