123456789_123456789_123456789_123456789_123456789_

Module: Mongoid::Findable

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, Forwardable
Defined in: lib/mongoid/findable.rb

Overview

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

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#empty? ⇒ true | false (readonly)

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.

[ GitHub ] 

  


# File 'lib/mongoid/findable.rb', line 94



def empty?
  count == 0
end


  







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.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 74



def count
  with_default_scope.count
end


  








  

    #estimated_count  ⇒ Integer 
  



  

    

Returns an estimated count of records in the database.


  





    

    
Examples:

        


Get the count of matching documents.



      
Person.estimated_count

  


Returns:


    
  
  • 
    (Integer)
—    
    

    The number of matching documents.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 84



def estimated_count
  with_default_scope.estimated_count
end


  








  

    #exists?(id_or_conditions = :none)  ⇒ true | false 
  



  

    

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


  





    

    
Examples:

        


Do any documents exist for the conditions?



      
Person.exists?

        


Do any documents exist for given _id.



      
Person.exists?(BSON::ObjectId(...))

        


Do any documents exist for given conditions.



      
Person.exists?(name: "...")

  


Parameters:


    
  
  • 
    id_or_conditions
    (Hash | Object | false)
    (defaults to: :none)
—    
    

    an _id to search for, a hash of conditions, nil or false.
    

    
  
    • 



Returns:


    
  
  • 
    (true | false)
—    
    

    If any documents exist for the conditions. Always false if passed nil or false.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 115



def exists?(id_or_conditions = :none)
  with_default_scope.exists?(id_or_conditions)
end


  








  

    #find(*args, &block)  ⇒ Document | Array<Document> | nil 
  



  

    
  

    Note:
    


Each argument can be an individual id, an array of ids or a nested array. Each array will be flattened.



  




Finds a Document or multiple documents by their _id values.



If a single non-Array argument is given, this argument is interpreted as the _id value of a document to find. If there is a matching document in the database, this document is returned; otherwise, if the raise_not_found_error ::Mongoid configuration option is truthy (which is the default), Errors::DocumentNotFound is raised, and if raise_not_found_error is falsy, find returns nil.



If multiple arguments are given, or an ::Array argument is given, the array is flattened and each array element is interpreted as the _id value of the document to find. ::Mongoid then attempts to retrieve all documents with the provided _id values. The return value is an array of found documents. Each document appears one time in the returned array, even if its _id is given multiple times in the argument to find. If the raise_not_found_error ::Mongoid configuration option is truthy, Errors::DocumentNotFound exception is raised if any of the specified _ids were not found in the database. If the raise_not_found_error ::Mongoid configuration option is falsy, only those documents which are found are returned; if no documents are found, the return value is an empty array.



Note that MongoDB does not allow the _id field to be an array.



The argument undergoes customary ::Mongoid type conversions based on the type declared for the _id field. By default the _id field is a BSON::ObjectId; this allows strings to be passed to find and the strings will be transparently converted to ::BSON::ObjectId instances during query construction.



If this method is given a block, it delegates to Enumerable#find and returns the first document of those found by the current Crieria object for which the block returns a truthy value. If both a block and ids are given, the block is ignored and the documents for the given ids are returned. If a block and a Proc are given, the method delegates to Enumerable#find and uses the proc as the default.



The find method takes into account the default scope defined on the model class, if any.


  





  
Parameters:


    
  
  • 
    *args
    ([ Object | Array<Object> ]...)
—    
    

    The id(s) to find.
    

    
  
    • 



Returns:



Raises:





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 168



def find(*args, &block)
  empty_or_proc = args.empty? || (args.length == 1 && args.first.is_a?(Proc))
  if block_given? && empty_or_proc
    with_default_scope.find(*args, &block)
  else
    with_default_scope.find(*args)
  end
end


  








  

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



  

    

Find the first Document given the conditions. If a matching Document is not found and ::Mongoid.raise_not_found_error is true it raises Mongoid::Errors::DocumentNotFound, return null nil elsewise.



and ::Mongoid.raise_not_found_error is true.


  





    

    
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:


    
  
  • 
    (Document | nil)
—    
    

    A matching document.
    

    
  
    • 



Raises:





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 191



def find_by(attrs = {})
  result = where(attrs).find_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_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:





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 211



def find_by!(attrs = {})
  result = where(attrs).find_first
  raise(Errors::DocumentNotFound.new(self, attrs)) unless result
  yield(result) if result && block_given?
  result
end


  








  

    #first(limit = nil)  ⇒ Document 
    Also known as: #one
  



  

    

Find the first Document given the conditions.


  





    

    
Examples:

        


Find the first document.



      
Person.first

  


Parameters:


    
  
  • 
    limit
    (Integer)
    (defaults to: nil)
—    
    

    The number of documents to return.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    The first matching document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 226



def first(limit = nil)
  with_default_scope.first(limit)
end


  








  

    #last(limit = nil)  ⇒ Document 
  



  

    

Find the last Document given the conditions.


  





    

    
Examples:

        


Find the last document.



      
Person.last

  


Parameters:


    
  
  • 
    limit
    (Integer)
    (defaults to: nil)
—    
    

    The number of documents to return.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    The last matching document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 239



def last(limit = nil)
  with_default_scope.last(limit)
end


  








  

    #one(limit = nil)  
  



  

    

Alias for #first.


  



  [ GitHub ]


  

  


# File 'lib/mongoid/findable.rb', line 229



alias :one :first