Module: Mongoid::Criteria::Modifiable

Included in:
Mongoid::Criteria
Defined in:
lib/mongoid/criteria/modifiable.rb

Overview

Mixin module for Mongoid::Criteria which adds the ability to build or create new documents with attributes initialized to the conditions of the criteria.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#create_attrs ⇒ Object (readonly)

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. 



14
15
16
 
# File 'lib/mongoid/criteria/modifiable.rb', line 14

def create_attrs
  @create_attrs
end

#create_attrs Additional attributes to add to the Document upon creation.(AdditionalattributestoaddtotheDocumentuponcreation.) ⇒ Object (readonly)

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. 



14
 
# File 'lib/mongoid/criteria/modifiable.rb', line 14

attr_reader :create_attrs

Instance Method Details

#build(attrs = {}, &block) ⇒ Document Also known as: new

Build a document given the selector and return it. Complex criteria, such as $in and $or operations will get ignored.

Examples:

build the document.

Person.where(:title => "Sir").build

Build with selectors getting ignored.

Person.where(:age.gt => 5).build

Returns:

  • (Document) —

    A non-persisted document.



26
27
28
 
# File 'lib/mongoid/criteria/modifiable.rb', line 26

def build(attrs = {}, &block)
  create_document(:new, attrs, &block)
end

#create(attrs = {}, &block) ⇒ Document

Create a document in the database given the selector and return it. Complex criteria, such as $in and $or operations will get ignored.

Examples:

Create the document.

Person.where(:title => "Sir").create

Create with selectors getting ignored.

Person.where(:age.gt => 5).create

Returns:

  • (Document) —

    A newly created document.



41
42
43
 
# File 'lib/mongoid/criteria/modifiable.rb', line 41

def create(attrs = {}, &block)
  create_document(:create, attrs, &block)
end

#create!(attrs = {}, &block) ⇒ Document

Create a document in the database given the selector and return it. Complex criteria, such as $in and $or operations will get ignored. If validation fails, an error will be raised.

Examples:

Create the document.

Person.where(:title => "Sir").create

Create with selectors getting ignored.

Person.where(:age.gt => 5).create

Returns:

  • (Document) —

    A newly created document.

Raises:



58
59
60
 
# File 'lib/mongoid/criteria/modifiable.rb', line 58

def create!(attrs = {}, &block)
  create_document(:create!, attrs, &block)
end

#create_with(attrs = {}) ⇒ Mongoid::Criteria

Define attributes with which new documents will be created.

Note that if ‘find_or_create_by` is called after this in a method chain, the attributes in the query will override those from this method.

Examples:

Define attributes to be used when a new document is created.

Person.create_with(job: 'Engineer').find_or_create_by(employer: 'MongoDB')

Returns:



71
72
73
74
75
76
 
# File 'lib/mongoid/criteria/modifiable.rb', line 71

def create_with(attrs = {})
  tap do
    @create_attrs ||= {}
    @create_attrs.update(attrs)
  end
end

#find_or_create_by(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or creates a new document with the conditions that were supplied.

Examples:

Find or create the document.

Person.find_or_create_by(:attribute => "value")

Parameters:

  • attrs (Hash) (defaults to: {}) —

    The attributes to check.

Returns:

  • (Document) —

    A matching or newly created document.



87
88
89
 
# File 'lib/mongoid/criteria/modifiable.rb', line 87

def find_or_create_by(attrs = {}, &block)
  find_or(:create, attrs, &block)
end

#find_or_create_by!(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or creates a new document with the conditions that were supplied. If validation fails an exception will be raised.

Examples:

Find or create the document.

Person.find_or_create_by!(:attribute => "value")

Parameters:

  • attrs (Hash) (defaults to: {}) —

    The attributes to check.

Returns:

  • (Document) —

    A matching or newly created document.

Raises:



103
104
105
 
# File 'lib/mongoid/criteria/modifiable.rb', line 103

def find_or_create_by!(attrs = {}, &block)
  find_or(:create!, attrs, &block)
end

#find_or_initialize_by(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or initializes a new document with the conditions that were supplied.

Examples:

Find or initialize the document.

Person.find_or_initialize_by(:attribute => "value")

Parameters:

  • attrs (Hash) (defaults to: {}) —

    The attributes to check.

Returns:

  • (Document) —

    A matching or newly initialized document.



116
117
118
 
# File 'lib/mongoid/criteria/modifiable.rb', line 116

def find_or_initialize_by(attrs = {}, &block)
  find_or(:new, attrs, &block)
end

#first_or_create(attrs = nil, &block) ⇒ Document

Find the first Document, or creates a new document with the conditions that were supplied plus attributes.

Examples:

First or create the document.

Person.where(name: "Jon").first_or_create(attribute: "value")

Parameters:

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

    The additional attributes to add.

Returns:

  • (Document) —

    A matching or newly created document.



129
130
131
 
# File 'lib/mongoid/criteria/modifiable.rb', line 129

def first_or_create(attrs = nil, &block)
  first_or(:create, attrs, &block)
end

#first_or_create!(attrs = nil, &block) ⇒ Document

Find the first Document, or creates a new document with the conditions that were supplied plus attributes and will raise an error if validation fails.

Examples:

First or create the document.

Person.where(name: "Jon").first_or_create!(attribute: "value")

Parameters:

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

    The additional attributes to add.

Returns:

  • (Document) —

    A matching or newly created document.



143
144
145
 
# File 'lib/mongoid/criteria/modifiable.rb', line 143

def first_or_create!(attrs = nil, &block)
  first_or(:create!, attrs, &block)
end

#first_or_initialize(attrs = nil, &block) ⇒ Document

Find the first Document, or initializes a new document with the conditions that were supplied plus attributes.

Examples:

First or initialize the document.

Person.where(name: "Jon").first_or_initialize(attribute: "value")

Parameters:

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

    The additional attributes to add.

Returns:

  • (Document) —

    A matching or newly initialized document.



156
157
158
 
# File 'lib/mongoid/criteria/modifiable.rb', line 156

def first_or_initialize(attrs = nil, &block)
  first_or(:new, attrs, &block)
end