Module: Mongoid::Finders

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

#all(*args) ⇒ Criteria

Find all documents that match the given conditions.

Examples:

Find all matching documents given conditions.

Person.all(:conditions => { :attribute => "value" })

Parameters:

  • args (Array) —

    The conditions with options.

Returns:

  • (Criteria) —

    The matching documents.



25
26
27
 
# File 'lib/mongoid/finders.rb', line 25

def all(*args)
  find(:all, *args)
end

#count(*args) ⇒ Integer

Returns a count of matching records in the database based on the provided arguments.

Examples:

Get the count of matching documents.

Person.count(:conditions => { :attribute => "value" })

Parameters:

  • args (Array) —

    The conditions.

Returns:

  • (Integer) —

    The number of matching documents.



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

def count(*args)
  find(:all, *args).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.



48
49
50
 
# File 'lib/mongoid/finders.rb', line 48

def empty?
  count == 0
end

#exists?(*args) ⇒ 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?(:conditions => { :attribute => "value" })

Parameters:

  • args (Array) —

    The conditions.

Returns:



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

def exists?(*args)
   find(:all, *args).count > 0
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 the first matching document.

Person.find(:first, :conditions => { :attribute => "value" })

Find all matching documents.

Person.find(:all, :conditions => { :attribute => "value" })

Find a single document by an id.

Person.find(BSON::ObjectId)

Parameters:

  • args (Array) —

    An assortment of finder options.

Returns:



83
84
85
 
# File 'lib/mongoid/finders.rb', line 83

def find(*args)
  criteria.find(*args)
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.



96
97
98
 
# File 'lib/mongoid/finders.rb', line 96

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.



109
110
111
 
# File 'lib/mongoid/finders.rb', line 109

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

#first(*args) ⇒ Document

Find the first Document given the conditions.

Examples:

Find the first document.

Person.first(:conditions => { :attribute => "value" })

Parameters:

  • args (Array) —

    The conditions with options.

Returns:

  • (Document) —

    The first matching document.



121
122
123
 
# File 'lib/mongoid/finders.rb', line 121

def first(*args)
  find(:first, *args)
end

#last(*args) ⇒ Document

Find the last Document given the conditions.

Examples:

Find the last document.

Person.last(:conditions => { :attribute => "value" })

Parameters:

  • args (Array) —

    The conditions with options.

Returns:

  • (Document) —

    The last matching document.



133
134
135
 
# File 'lib/mongoid/finders.rb', line 133

def last(*args)
  find(:last, *args)
end