123456789_123456789_123456789_123456789_123456789_

Module: Mongoid::Criteria::Findable

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::Mongoid::Criteria
Defined in: lib/mongoid/criteria/findable.rb

Overview

Mixin module included in ::Mongoid::Criteria which adds the ability to find document by id.

Instance Method Summary

Instance Method Details

#execute_or_raise(ids, multi) ⇒ Document | Array<Document>

Execute the criteria or raise an error if no documents found.

Examples:

Execute or raise

criteria.execute_or_raise(id)

Parameters:

  • ids (Object) —

    The arguments passed.

  • multi (true | false) —

    Whether there arguments were a list, and therefore the return value should be an array.

Returns:

Raises:

[ GitHub ] 

  


# File 'lib/mongoid/criteria/findable.rb', line 23



def execute_or_raise(ids, multi)
  result = multiple_from_db(ids)
  check_for_missing_documents!(result, ids)
  multi ? result : result.first
end


  








  

    #find(*args)  ⇒ Document | Array<Document> 
  



  

    
  

    Note:
    


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



  




Find the matching document(s) in the criteria for the provided id(s).


  





    

    
Examples:

        


Find by an id.



      
criteria.find(BSON::ObjectId.new)

        


Find by multiple ids.



      
criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])

  


Parameters:


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

    The id(s) to find.
    

    
  
    • 



Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 43



def find(*args)
  ids = prepare_ids_for_find(args)
  raise_invalid if ids.any?(&:nil?)
  for_ids(ids).execute_or_raise(ids, multi_args?(args))
end


  








  

    #for_ids(ids)  ⇒ Criteria 
  



  

    

Adds a criterion to the Criteria that specifies an id that must be matched.


  





    

    
Examples:

        


Add a single id criteria.



      
criteria.for_ids([ 1 ])

        


Add multiple id criteria.



      
criteria.for_ids([ 1, 2 ])

  


Parameters:


    
  
  • 
    ids
    (Array)
—    
    

    The array of ids.
    

    
  
    • 



Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 60



def for_ids(ids)
  ids = mongoize_ids(ids)
  if ids.size > 1
    send(id_finder, { _id: { "$in" => ids }})
  else
    send(id_finder, { _id: ids.first })
  end
end


  








  

    #from_database(ids)  ⇒ Array<Document>  (private)
  

  

    This method is for internal use only.
  



  

    

Get documents from the database only.


  





    

    
Examples:

        


Get documents from the database.



      
criteria.from_database(ids)

  


Parameters:


    
  
  • 
    ids
    (Array<Object>)
—    
    

    The ids to fetch with.
    

    
  
    • 



Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 108



def from_database(ids)
  from_database_selector(ids).entries
end


  








  

    #from_database_selector(ids)   (private)
  

  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 112



def from_database_selector(ids)
  if ids.size > 1
    any_in(_id: ids)
  else
    where(_id: ids.first)
  end
end


  








  

    #id_finder  ⇒ Symbol  (private)
  

  

    This method is for internal use only.
  



  

    

Get the finder used to generate the id query.


  





    

    
Examples:

        


Get the id finder.



      
criteria.id_finder

  


Returns:


    
  
  • 
    (Symbol)
—    
    

    The name of the finder method.
    

    
  
    • 





  [ GitHub ]


  

  


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



def id_finder
  @id_finder ||= extract_id ? :all_of : :where
end


  








  

    #mongoize_ids(ids)  ⇒ Array<Object>  (private)
  

  

    This method is for internal use only.
  



  

    

Convert all the ids to their proper types.


  





    

    
Examples:

        


Convert the ids.



      
criteria.mongoize_ids(ids)

  


Parameters:


    
  
  • 
    ids
    (Array<Object>)
—    
    

    The ids to convert.
    

    
  
    • 



Returns:


    
  
  • 
    (Array<Object>)
—    
    

    The converted ids.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 130



def mongoize_ids(ids)
  ids.map do |id|
    id = id[:_id] if id.respond_to?(:keys) && id[:_id]
    klass.fields["_id"].mongoize(id)
  end
end


  








  

    #multi_args?(args)  ⇒ true | false  (private)
  



  

    

Indicates whether the given arguments array is a list of values. Used by the find method to determine whether to return an array or single value.


  





    

    
Examples:

        


Are these arguments a list of values?



      
multi_args?([ 1, 2, 3 ]) #=> true

  


Parameters:


    
  
  • 
    args
    (Array)
—    
    

    The arguments.
    

    
  
    • 



Returns:


    
  
  • 
    (true | false)
—    
    

    Whether the arguments are a list.
    

    
  
    • 





  [ GitHub ]


  

  


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



def multi_args?(args)
  args.size > 1 || !args.first.is_a?(Hash) && args.first.resizable?
end


  








  

    #multiple_from_db(ids)  ⇒ Array<Document> 
  



  

    

Get the documents from the identity map, and if not found hit the database.


  





    

    
Examples:

        


Get the documents from the map or criteria.



      
criteria.multiple_from_map_or_db(ids)

  


Parameters:


    
  
  • 
    ids
    (Array<Object>)
—    
    

    The searched ids.
    

    
  
    • 



Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 78



def multiple_from_db(ids)
  return entries if embedded?
  ids = mongoize_ids(ids)
  ids.empty? ? [] : from_database(ids)
end


  








  

    #prepare_ids_for_find(args)  ⇒ Array  (private)
  



  

    

Convert args to the #find method into a flat array of ids.


  





    

    
Examples:

        


Get the ids.



      
prepare_ids_for_find([ 1, [ 2, 3 ] ])

  


Parameters:


    
  
  • 
    args
    (Array<Object>)
—    
    

    The arguments.
    

    
  
    • 



Returns:


    
  
  • 
    (Array)
—    
    

    The array of ids.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 145



def prepare_ids_for_find(args)
  args.flat_map do |arg|
    case arg
    when Array, Set
      prepare_ids_for_find(arg)
    when Range
      arg.begin&.numeric? && arg.end&.numeric? ? arg.to_a : arg
    else
      arg
    end
  end.uniq(&:to_s)
end


  








  

    #raise_invalid   (private)
  



  

    

Convenience method of raising an invalid options error.


  





    

    
Examples:

        


Raise the error.



      
criteria.raise_invalid

  


Raises:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/findable.rb', line 178



def raise_invalid
  raise Errors::InvalidFind.new
end