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(&: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

#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.



137
138
139
 
# File 'lib/mongoid/criterion/inclusion.rb', line 137

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.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/mongoid/criterion/inclusion.rb', line 153

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!)
        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