Module: Mongoid::Criterion::Inclusion

Included in:
Mongoid::Criteria
Defined in:
lib/mongoid/criterion/inclusion.rb

Instance Method Summary collapse

Instance Method Details

#all(attributes = {}) ⇒ Criteria Also known as: all_in

Adds a criterion to the Criteria that specifies values that must all be matched in order to return results. Similar to an “in” clause but the underlying conditional logic is an “AND” and not an “OR”. The MongoDB conditional operator that will be used is “$all”.

Examples:

Adding the criterion.

criteria.all(:field => ["value1", "value2"])
criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])

Parameters:

  • attributes (Hash) (defaults to: {}) —

    Name/value pairs that all must match.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



18
19
20
 
# File 'lib/mongoid/criterion/inclusion.rb', line 18

def all(attributes = {})
  update_selector(attributes, "$all")
end

#also_in(attributes = {}) ⇒ Criteria

Adds a criterion to the Criteria that specifies values where any can be matched in order to return results. This is similar to an SQL “IN” clause. The MongoDB conditional operator that will be used is “$in”. Any previously matching “$in” arrays will be unioned with new arguments.

Examples:

Adding the criterion.

criteria.in(:field => ["value1"]).also_in(:field => ["value2"])

Parameters:

  • attributes (Hash) (defaults to: {}) —

    Name/value pairs any can match.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



35
36
37
 
# File 'lib/mongoid/criterion/inclusion.rb', line 35

def also_in(attributes = {})
  update_selector(attributes, "$in")
end

#and(selector = nil) ⇒ Criteria

Adds a criterion to the Criteria that specifies values that must be matched in order to return results. This is similar to a SQL “WHERE” clause. This is the actual selector that will be provided to MongoDB, similar to the Javascript object that is used when performing a find() in the MongoDB console.

Examples:

Adding the criterion.

criteria.and(:field1 => "value1", :field2 => 15)

Parameters:

  • selectior (Hash) —

    Name/value pairs that all must match.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



51
52
53
 
# File 'lib/mongoid/criterion/inclusion.rb', line 51

def and(selector = nil)
  where(selector)
end

#any_of(*args) ⇒ Criteria Also known as: or

Adds a criterion to the Criteria that specifies a set of expressions to match if any of them return true. This is a $or query in MongoDB and is similar to a SQL OR. This is named #any_of and aliased “or” for readability.

Examples:

Adding the criterion.

criteria.any_of({ :field1 => "value" }, { :field2 => "value2" })

Parameters:

  • args (Array<Hash>) —

    A list of name/value pairs any can match.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



66
67
68
69
70
71
72
73
 
# File 'lib/mongoid/criterion/inclusion.rb', line 66

def any_of(*args)
  clone.tap do |crit|
    criterion = @selector["$or"] || []
    converted = BSON::ObjectId.convert(klass, args.flatten)
    expanded = converted.collect { |hash| hash.expand_complex_criteria }
    crit.selector["$or"] = criterion.concat(expanded)
  end
end

#find(*args) ⇒ Document, Criteria

TODO:

Durran: DRY up duplicated code in a few places.

Find the matchind document in the criteria, either based on id or conditions.

Examples:

Find by an id.

criteria.find(BSON::ObjectId.new)

Find by multiple ids.

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

Conditionally find all matching documents.

criteria.find(:all, :conditions => { :title => "Sir" })

Conditionally find the first document.

criteria.find(:first, :conditions => { :title => "Sir" })

Conditionally find the last document.

criteria.find(:last, :conditions => { :title => "Sir" })

Parameters:

Returns:



101
102
103
104
105
106
107
108
109
110
 
# File 'lib/mongoid/criterion/inclusion.rb', line 101

def find(*args)
  type, crit = search(*args)
  case type
  when :first then crit.one
  when :last then crit.last
  when :ids then execute_or_raise(args, crit)
  else
    crit
  end
end

#in(attributes = {}) ⇒ Criteria Also known as: any_in

Adds a criterion to the Criteria that specifies values where any can be matched in order to return results. This is similar to an SQL “IN” clause. The MongoDB conditional operator that will be used is “$in”.

Examples:

Adding the criterion.

criteria.in(:field => ["value1", "value2"])
criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])

Parameters:

  • attributes (Hash) (defaults to: {}) —

    Name/value pairs any can match.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



123
124
125
 
# File 'lib/mongoid/criterion/inclusion.rb', line 123

def in(attributes = {})
  update_selector(attributes, "$in", :&)
end

#includes(*relations) ⇒ Criteria

Note:

This will only work if Mongoid’s identity map is enabled. To do so set identity_map_enabled: true in your mongoid.yml

Note:

This will work for embedded relations 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 relations. Will load all the documents into the identity map who’s ids match based on the extra query for the ids.

Examples:

Eager load the provided relations.

Person.includes(:posts, :game)

Parameters:

  • relations (Array<Symbol>) —

    The names of the relations to eager load.

Returns:

Since:

  • 2.2.0



152
153
154
155
156
157
 
# File 'lib/mongoid/criterion/inclusion.rb', line 152

def includes(*relations)
  relations.each do |name|
    inclusions.push(klass.reflect_on_association(name))
  end
  clone
end

#inclusions ⇒ Array<Metadata>

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

Examples:

Get the eager loading inclusions.

Person.includes(:game).inclusions

Returns:

  • (Array<Metadata>) —

    The inclusions.

Since:

  • 2.2.0



167
168
169
 
# File 'lib/mongoid/criterion/inclusion.rb', line 167

def inclusions
  @inclusions ||= []
end

#load_ids(key) ⇒ Array<String, BSON::ObjectId>

Loads an array of ids only for the current criteria. Used by eager loading to determine the documents to load.

Examples:

Load the related ids.

criteria.load_ids("person_id")

Parameters:

  • key (String) —

    The id or foriegn key string.

Returns:

Since:

  • 2.2.0



182
183
184
 
# File 'lib/mongoid/criterion/inclusion.rb', line 182

def load_ids(key)
  driver.find(selector, { :fields => { key => 1 }}).map { |doc| doc[key] }
end

#near(attributes = {}) ⇒ Criteria

Adds a criterion to the Criteria that specifies values to do geospacial searches by. The field must be indexed with the “2d” option.

Examples:

Adding the criterion.

criteria.near(:field1 => [30, -44])

Parameters:

  • attributes (Hash) (defaults to: {}) —

    The fields with lat/long values.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



195
196
197
 
# File 'lib/mongoid/criterion/inclusion.rb', line 195

def near(attributes = {})
  update_selector(attributes, "$near")
end

#where(selector = nil) ⇒ Criteria

Adds a criterion to the Criteria that specifies values that must be matched in order to return results. This is similar to a SQL “WHERE” clause. This is the actual selector that will be provided to MongoDB, similar to the Javascript object that is used when performing a find() in the MongoDB console.

Examples:

Adding the criterion.

criteria.where(:field1 => "value1", :field2 => 15)

Parameters:

  • selector (Hash) (defaults to: nil) —

    Name/value pairs where all must match.

Returns:

  • (Criteria) —

    A new criteria with the added selector.



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/mongoid/criterion/inclusion.rb', line 211

def where(selector = nil)
  clone.tap do |crit|
    selector = case selector
      when String then {"$where" => selector}
      else
        BSON::ObjectId.convert(klass, selector || {}, false).expand_complex_criteria
    end

    selector.each_pair do |key, value|
      if crit.selector.has_key?(key) &&
        crit.selector[key].respond_to?(:merge!) &&
        value.respond_to?(:merge!)
        crit.selector[key] =
          crit.selector[key].merge!(value) do |key, old, new|
            key == '$in' ? old & new : new
          end
      else
        crit.selector[key] = value
      end
    end
  end
end