Module: Mongoid::Document

Extended by:
ActiveSupport::Concern
Includes:
Composable, Touchable::InstanceMethods
Included in:
Comment, GlobalDiscriminatorKeyAssignment::InvalidFieldHost, Post
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::INVALID_BSON_CLASSES, Fields::StringifiedSymbol, Fields::TYPE_MAPPINGS

Constants included from Atomic

Atomic::UPDATES

Instance Attribute Summary collapse

Attributes included from Stateful

#destroyed, #flagged_for_destroy, #previously_new_record

Attributes included from Association

#_association

Attributes included from Attributes

#attributes

Attributes included from Clients::StorageOptions

#remembered_storage_options

Instance Method Summary collapse

Methods included from Touchable::InstanceMethods

#_clear_touch_updates, #_gather_touch_updates, #_run_touch_callbacks_from_root, #_touchable_parent?, #suppress_touch_callbacks, #touch, #touch_callbacks_suppressed?

Methods included from Composable

prohibited_methods

Methods included from Equality

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

Methods included from Copyable

#clone

Methods included from Interceptable

#_mongoid_run_child_after_callbacks, #_mongoid_run_child_before_callbacks, #_mongoid_run_child_callbacks, #_mongoid_run_child_callbacks_with_around, #_mongoid_run_child_callbacks_without_around, #callback_executable?, #in_callback_state?, #pending_callbacks, #pending_callbacks=, #run_after_callbacks, #run_before_callbacks, #run_callbacks, #run_pending_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=, #new_record?, #persisted?, #previously_new_record?, #previously_persisted?, #pushable?, #readonly!, #readonly?, #settable?, #updateable?

Methods included from Shardable

#shard_key_field_value, #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::Multipliable

#mul

Methods included from Persistable::Minable

#set_min

Methods included from Persistable::Maxable

#set_max

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 Fields

#apply_default, #apply_defaults, #apply_post_processed_defaults, #apply_pre_processed_defaults, #attribute_names, database_field_name, #database_field_name, #dot_dollar_field?, #lazy_settable?, option, options, traverse_association_tree, #using_object_ids?, #validate_writable_field_name!

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?, #process_raw_attribute, #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

included

Methods included from Clients::Options

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

Methods included from Clients::StorageOptions

#remember_storage_options!, #storage_options

Methods included from Changeable

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

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.



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

def __selected_fields
  @__selected_fields
end

#new_record ⇒ Object (readonly)

Returns the value of attribute new_record.



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

def new_record
  @new_record
end

Instance Method Details

#_handle_callbacks_after_instantiation(execute_callbacks) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Handles the setup and execution of callbacks, if callbacks are to be executed; otherwise, adds the appropriate callbacks to the pending callbacks list.

Parameters:

  • execute_callbacks (true | false) —

    Whether callbacks should be executed or not.



211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/mongoid/document.rb', line 211

def _handle_callbacks_after_instantiation(execute_callbacks)
  if execute_callbacks
    apply_defaults
    yield self if block_given?
    run_callbacks(:find) unless _find_callbacks.empty?
    run_callbacks(:initialize) unless _initialize_callbacks.empty?
  else
    yield self if block_given?
    self.pending_callbacks += %i[ apply_defaults find initialize ]
  end
end

#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.



134
135
136
 
# File 'lib/mongoid/document.rb', line 134

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.



156
157
158
159
160
161
162
163
 
# File 'lib/mongoid/document.rb', line 156

def as_json(options = nil)
  rv = super
  if options && options[:compact]
    Mongoid::Warnings.warn_as_json_compact_deprecated
    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



176
177
178
179
180
181
182
183
 
# File 'lib/mongoid/document.rb', line 176

def becomes(klass)
  mongoid_document_check!(klass)

  became = klass.new(clone_document)
  became.internal_state = internal_state

  became
end

#freeze ⇒ Document

Freezes the internal attributes of the document.

Examples:

Freeze the document

document.freeze

Returns:



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

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.



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

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.



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

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]



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

def identity
  [ self.class, _id ]
end

#initialize(attrs = nil, &block) ⇒ 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:



102
103
104
 
# File 'lib/mongoid/document.rb', line 102

def initialize(attrs = nil, &block)
  construct_document(attrs, &block)
end

#internal_state=(state) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Sets the internal state of this document. Used only by #becomes to help initialize a retyped document.

Parameters:

  • state (Hash) —

    The map of internal state values.



191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/mongoid/document.rb', line 191

def internal_state=(state)
  self._id = state[:id]
  @changed_attributes = state[:changed_attributes]
  @errors = ActiveModel::Errors.new(self).tap { |e| e.copy!(state[:errors]) }
  @new_record = state[:new_record]
  @destroyed = state[:destroyed]

  update_discriminator(state[:discriminator_key_was])

  mark_persisted_state_for_embedded_documents(state[:new_record])
end

#model_name ⇒ String

Return the model name of the document.

Examples:

Return the model name.

document.model_name

Returns:

  • (String) —

    The model name.



112
113
114
 
# File 'lib/mongoid/document.rb', line 112

def model_name
  self.class.model_name
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.



122
123
124
 
# File 'lib/mongoid/document.rb', line 122

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