Module: Mongoid::Finders

Extended by:
Origin::Forwardable
Defined in:
lib/mongoid/finders.rb

Overview

This module defines the finder methods that hang off the document at the class level.

Instance Method Summary collapse

Instance Method Details

#count ⇒ Integer

Returns a count of records in the database. If you want to specify conditions use where.

Examples:

Get the count of matching documents.

Person.count
Person.where(title: "Sir").count

Returns:

  • (Integer) —

    The number of matching documents.



21
22
23
 
# File 'lib/mongoid/finders.rb', line 21

def count
  with_default_scope.count
end

#empty? ⇒ true, false

Returns true if count is zero

Examples:

Are there no saved documents for this model?

Person.empty?

Returns:

  • (true, false) —

    If the collection is empty.



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

def empty?
  count == 0
end

#exists? ⇒ Boolean

Returns true if there are on document in database based on the provided arguments.

Examples:

Do any documents exist for the conditions?

Person.exists?

Parameters:

  • args (Array) —

    The conditions.

Returns:



42
43
44
 
# File 'lib/mongoid/finders.rb', line 42

def exists?
  with_default_scope.exists?
end

#find(*args) ⇒ Document, ...

Find a Document in several different ways.

If a String is provided, it will be assumed that it is a representation of a Mongo::ObjectID and will attempt to find a single Document based on that id. If a Symbol and Hash is provided then it will attempt to find either a single Document or multiples based on the conditions provided and the first parameter.

Examples:

Find a single document by an id.

Person.find(Moped::BSON::ObjectId)

Parameters:

  • args (Array) —

    An assortment of finder options.

Returns:



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

def find(*args)
  with_default_scope.find(*args)
end

#find_by(attrs = {}) {|result| ... } ⇒ Document

Find the first Document given the conditions, or raises Mongoid::Errors::DocumentNotFound

Examples:

Find the document by attribute other than id

Person.find_by(:username => "superuser")

Parameters:

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

    The attributes to check.

Yields:

  • (result)

Returns:

Raises:

Since:

  • 3.0.0



103
104
105
106
107
108
109
110
 
# File 'lib/mongoid/finders.rb', line 103

def find_by(attrs = {})
  result = where(attrs).first
  if result.nil? && Mongoid.raise_not_found_error
    raise(Errors::DocumentNotFound.new(self, attrs))
  end
  yield(result) if result && block_given?
  result
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.



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

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.



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

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

#first ⇒ Document

Find the first Document given the conditions.

Examples:

Find the first document.

Person.first

Returns:

  • (Document) —

    The first matching document.



118
119
120
 
# File 'lib/mongoid/finders.rb', line 118

def first
  with_default_scope.first
end

#last ⇒ Document

Find the last Document given the conditions.

Examples:

Find the last document.

Person.last

Returns:

  • (Document) —

    The last matching document.



128
129
130
 
# File 'lib/mongoid/finders.rb', line 128

def last
  with_default_scope.last
end