123456789_123456789_123456789_123456789_123456789_

Module: Mongoid::Criteria::Includable

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

Overview

Module providing functionality for parsing (nested) inclusion definitions.

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#inclusions ⇒ Array<Mongoid::Association::Relatable> (rw)

Get a list of criteria that are to be executed for eager loading.

Returns:

[ GitHub ] 

  


# File 'lib/mongoid/criteria/includable.rb', line 37



def inclusions
  @inclusions ||= []
end


  








  

    #inclusions=(value)  ⇒ Array<Mongoid::Association::Relatable>  (rw)
  



  

    

::Set the inclusions for the criteria.


  





  
Parameters:



Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/includable.rb', line 46



def inclusions=(value)
  @inclusions = value
end


  







Instance Method Details



  

    #add_inclusion(association, parent = nil)   (private)
  



  

    

Add an inclusion definition to the list of inclusions for the criteria.


  





  
Parameters:


    
  
  • 
    association
    (Mongoid::Association::Relatable)
—    
    

    The association metadata.
    

    
  
    • 
  
  • 
    parent
    (String)
    (defaults to: nil)
—    
    

    The name of the association above this one in the inclusion tree, if it is a nested inclusion.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/includable.rb', line 57



def add_inclusion(association, parent = nil)
  if assoc = inclusions.detect { |a| a == association }
    assoc.parent_inclusions.push(parent) if parent
  else
    assoc = association.dup
    assoc.parent_inclusions = []
    assoc.parent_inclusions.push(parent) if parent
    inclusions.push(assoc)
  end
end


  








  

    #extract_includes_list(_parent_class, parent, *relations_list)   (private)
  



  

    

Iterate through the list of relations and create the inclusions list.


  





  
Parameters:


    
  
  • 
    _parent_class
    (Class | String | Symbol)
—    
    

    The class from which the association originates.
    

    
  
    • 
  
  • 
    parent
    (String)
—    
    

    The name of the association above this one in the inclusion tree, if it is a nested inclusion.
    

    
  
    • 
  
  • 
    *relations_list
    ([ Symbol | Hash | Array<Symbol | Hash> ]...)
—    
    

    The names of the association(s) to eager load.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/includable.rb', line 76



def extract_includes_list(_parent_class, parent, *relations_list)
  relations_list.flatten.each do |relation_object|
    if relation_object.is_a?(Hash)
      relation_object.each do |relation, _includes|
        association = _parent_class.reflect_on_association(relation)
        raise Errors::InvalidIncludes.new(_klass, [ relation ]) unless association
        add_inclusion(association, parent)
        extract_includes_list(association.klass, association.name, _includes)
      end
    else
      association = _parent_class.reflect_on_association(relation_object)
      raise Errors::InvalidIncludes.new(_parent_class, [ relation_object ]) unless association
      add_inclusion(association, parent)
    end
  end
end


  








  

    #includes(*relations)  ⇒ Criteria 
  



  

    
  

    Note:
    


This will work for embedded associations that reference another collection via belongs_to as well.



  


  

    Note:
    


Eager loading brings all the documents into memory, so there is a sweet spot on the performance gains. Internal benchmarks show that eager loading becomes slower around 100k documents, but this will naturally depend on the specific application.



  




Eager loads all the provided associations. Will load all the documents into the identity map whose ids match based on the extra query for the ids.


  





    

    
Examples:

        


Eager load the provided associations.



      
Person.includes(:posts, :game)

  


Parameters:


    
  
  • 
    *relations
    ([ Symbol | Hash ]...)
—    
    

    The names of the association(s) to eager load.
    

    
  
    • 



Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/includable.rb', line 29



def includes(*relations)
  extract_includes_list(klass, nil, relations)
  clone
end