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 60



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 69



def inclusions=(value)
  @inclusions = value
end


  








  

    #use_lookup?  ⇒ true | false  (readonly)
  



  

    

Returns whether to use $lookup aggregation for eager loading.


  





  
Returns:


    
  
  • 
    (true | false)
—    
    

    Whether to use $lookup.
    

    
  
    • 





  [ GitHub ]


  

  


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



def use_lookup?
  !!@use_lookup
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 80



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


  








  

    #eager_load(*relations)  ⇒ Criteria 
  



  

    

Eager loads all the provided associations using aggregation $lookup. The behavior should be identical to #includes.


  





    

    
Examples:

        


Eager load the provided associations.



      
Person.eager_load(:posts, :game)

  


Parameters:


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

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

    
  
    • 



Returns:





  [ GitHub ]


  

  


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



def eager_load(*relations)
  extract_includes_list(klass, nil, true, *relations)
  @use_lookup = !embedded?
  clone
end


  








  

    #extract_includes_list(_parent_class, parent, is_eager_load = false, *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.
    

    
  
    • 
  
  • 
    is_eager_load
    (Boolean)
    (defaults to: false)
—    
    

    Whether this is an eager load operation.
    

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

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

    
  
    • 





  [ GitHub ]


  

  


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



def extract_includes_list(_parent_class, parent, is_eager_load = false, *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_eager_error(is_eager_load, _klass, relation) unless association
        add_inclusion(association, parent)
        extract_includes_list(association.klass, association.name, is_eager_load, _includes)
      end
    else
      association = _parent_class.reflect_on_association(relation_object)
      raise_eager_error(is_eager_load, _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, false, *relations)
  clone
end