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. 



11
12
13
 
# File 'lib/mongoid/criteria/modifiable.rb', line 11

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. 



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

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.



23
24
25
 
# File 'lib/mongoid/criteria/modifiable.rb', line 23

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.



38
39
40
 
# File 'lib/mongoid/criteria/modifiable.rb', line 38

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:



55
56
57
 
# File 'lib/mongoid/criteria/modifiable.rb', line 55

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:



68
69
70
71
72
73
 
# File 'lib/mongoid/criteria/modifiable.rb', line 68

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.



84
85
86
 
# File 'lib/mongoid/criteria/modifiable.rb', line 84

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:



100
101
102
 
# File 'lib/mongoid/criteria/modifiable.rb', line 100

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.



113
114
115
 
# File 'lib/mongoid/criteria/modifiable.rb', line 113

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.



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

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.



140
141
142
 
# File 'lib/mongoid/criteria/modifiable.rb', line 140

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.



153
154
155
 
# File 'lib/mongoid/criteria/modifiable.rb', line 153

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