Module: Mongoid::Criteria::Queryable::Selectable

Extended by:
Macroable
Defined in:
lib/mongoid/criteria/queryable/selectable.rb

Overview

An queryable selectable is selectable, in that it has the ability to select document from the database. The selectable module brings all functionality to the selectable that has to do with building MongoDB selectors.

Constant Summary collapse

LINE_STRING =

Constant for a LineString $geometry.

'LineString'
POINT =

Constant for a Point $geometry.

'Point'
POLYGON =

Constant for a Polygon $geometry.

'Polygon'
ALLOWED_QUERY_OPERATORS =

Operators permitted at the top level of a query expression without opt-in. Excludes $where (JS execution) and other operators not needed for ordinary application queries.

%w[
  $and $or $nor $not $text $comment $expr $jsonSchema $alwaysFalse $alwaysTrue
].freeze
JAVASCRIPT_QUERY_OPERATORS =

Operators that execute server-side JavaScript. These are rejected at any depth, not just at the top level: the allowlist above permits $expr and the logical operators, and their values are arbitrary nested expressions that can carry $function or $where.

%w[$where $function $accumulator].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Macroable

key

Instance Attribute Details

#negating ⇒ Object

Returns the value of attribute negating.



23
24
25
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 23

def negating
  @negating
end

#negating If the next expression is negated.(Ifthe) ⇒ Object 



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

attr_accessor :negating, :selector

#selector ⇒ Object

Returns the value of attribute selector.



23
24
25
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 23

def selector
  @selector
end

#selector The query selector.(Thequeryselector.) ⇒ Object 



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

attr_accessor :negating, :selector

Class Method Details

.forwardables ⇒ Array<Symbol>

Get the methods on the selectable that can be forwarded to from a model.

Examples:

Get the forwardable methods.

Selectable.forwardables

Returns:

  • (Array<Symbol>) —

    The names of the forwardable methods.



999
1000
1001
1002
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 999

def forwardables
  public_instance_methods(false) -
    i[negating negating= negating? selector selector=]
end

Instance Method Details

#all(*criteria) ⇒ Selectable Also known as: all_in

Add the $all criterion.

Examples:

Add the criterion.

selectable.all(field: [ 1, 2 ])

Execute an $all in a where query.

selectable.where(:field.all => [ 1, 2 ])

Parameters:

  • *criteria (Hash...) —

    The key value pair(s) for $all matching.

Returns:



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 36

def all(*criteria)
  if criteria.empty?
    return clone.tap do |query|
      query.reset_strategies!
    end
  end

  criteria.inject(clone) do |query, condition|
    raise Errors::CriteriaArgumentRequired, :all if condition.nil?

    condition = expand_condition_to_array_values(condition)

    if strategy
      send(strategy, condition, '$all')
    else
      condition.inject(query) do |_query, (field, value)|
        v = { '$all' => value }
        v = { '$not' => v } if negating?
        _query.add_field_expression(field.to_s, v)
      end
    end
  end.reset_strategies!
end

#and(*criteria) ⇒ Selectable Also known as: all_of

Add the $and criterion.

Examples:

Add the criterion.

selectable.and({ field: value }, { other: value })

Parameters:

  • *criteria ([ Hash | Criteria | Array<Hash | Criteria> ]...) —

    Multiple key/value pair matches or Criteria objects that all must match to return results.

Returns:



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 72

def and(*criteria)
  _mongoid_flatten_arrays(criteria).inject(clone) do |c, new_s|
    new_s = new_s.selector if new_s.is_a?(Selectable)
    normalized = _mongoid_expand_keys(new_s)
    normalized.each do |k, v|
      k = k.to_s
      if c.selector[k]
        # There is already a condition on k.
        # If v is an operator, and all existing conditions are
        # also operators, and v isn't present in existing conditions,
        # we can add to existing conditions.
        # Otherwise use $and.
        if v.is_a?(Hash) &&
           v.length == 1 &&
           (new_k = v.keys.first).start_with?('$') &&
           (existing_kv = c.selector[k]).is_a?(Hash) &&
           !existing_kv.key?(new_k) &&
           existing_kv.keys.all? { |sub_k| sub_k.start_with?('$') }
          merged_v = c.selector[k].merge(v)
          c.selector.store(k, merged_v)
        else
          c = c.send(:__multi__, [ { k => v } ], '$and')
        end
      else
        c.selector.store(k, v)
      end
    end
    c
  end
end

#any_of(*criteria) ⇒ Selectable

Adds a disjunction of the arguments as an additional constraint to the criteria already existing in the receiver.

Use or to make the receiver one of the disjunction operands.

Each argument can be a Hash, a Criteria object, an array of Hash or Criteria objects, or a nested array. Nested arrays will be flattened and can be of any depth. Passing arrays is deprecated.

Examples:

Add the $or selection where both fields must have the specified values.

selectable.any_of(field: 1, field: 2)

Add the $or selection where either value match is sufficient.

selectable.any_of({field: 1}, {field: 2})

Same as previous example but using the deprecated array wrap.

selectable.any_of([{field: 1}, {field: 2}])

Same as previous example, also deprecated.

selectable.any_of([{field: 1}], [{field: 2}])

Parameters:

  • *criteria ([ Hash | Criteria | Array<Hash | Criteria> ]...) —

    Multiple key/value pair matches or Criteria objects, or arrays thereof. Passing arrays is deprecated.

Returns:



633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 633

def any_of(*criteria)
  criteria = _mongoid_flatten_arrays(criteria)
  case criteria.length
  when 0
    clone
  when 1
    # When we have a single criteria, any_of behaves like and.
    # Note: criteria can be a Query object, which #where method does
    # not support.
    self.and(*criteria)
  else
    # When we have multiple criteria, combine them all with $or
    # and add the result to self.
    exprs = criteria.map do |criterion|
      if criterion.is_a?(Selectable)
        _mongoid_expand_keys(criterion.selector)
      else
        Hash[criterion.map do |k, v|
          if k.is_a?(Symbol)
            [ k.to_s, v ]
          else
            [ k, v ]
          end
        end]
      end
    end
    self.and('$or' => exprs)
  end
end

#between(criterion) ⇒ Selectable

Add the range selection.

Examples:

Match on results within a single range.

selectable.between(field: 1..2)

Match on results between multiple ranges.

selectable.between(field: 1..2, other: 5..7)

Parameters:

  • criterion (Hash) —

    Multiple key/range pairs.

Returns:

Raises:



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 115

def between(criterion)
  raise Errors::CriteriaArgumentRequired, :between if criterion.nil?

  selection(criterion) do |selector, field, value|
    selector.store(
      field,
      { '$gte' => value.min, '$lte' => value.max }
    )
  end
end

#elem_match(criterion) ⇒ Selectable

Select with an $elemMatch.

Examples:

Add criterion for a single match.

selectable.elem_match(field: { name: "value" })

Add criterion for multiple matches.

selectable.elem_match(
  field: { name: "value" },
  other: { name: "value"}
)

Execute an $elemMatch in a where query.

selectable.where(:field.elem_match => { name: "value" })

Parameters:

  • criterion (Hash) —

    The field/match pairs.

Returns:

Raises:



143
144
145
146
147
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 143

def elem_match(criterion)
  raise Errors::CriteriaArgumentRequired, :elem_match if criterion.nil?

  and_with_operator(criterion, '$elemMatch')
end

#eq(criterion) ⇒ Selectable

Add the $eq criterion to the selector.

Examples:

Add the $eq criterion.

selectable.eq(age: 60)

Execute an $eq in a where query.

selectable.where(:field.eq => 10)

Parameters:

  • criterion (Hash) —

    The field/value pairs to check.

Returns:

Raises:



240
241
242
243
244
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 240

def eq(criterion)
  raise Errors::CriteriaArgumentRequired, :eq if criterion.nil?

  and_with_operator(criterion, '$eq')
end

#exists(criterion) ⇒ Selectable

Add the $exists selection.

Examples:

Add a single selection.

selectable.exists(field: true)

Add multiple selections.

selectable.exists(field: true, other: false)

Execute an $exists in a where query.

selectable.where(:field.exists => true)

Parameters:

  • criterion (Hash) —

    The field/boolean existence checks.

Returns:

Raises:



164
165
166
167
168
169
170
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 164

def exists(criterion)
  raise Errors::CriteriaArgumentRequired, :exists if criterion.nil?

  typed_override(criterion, '$exists') do |value|
    Mongoid::Boolean.evolve(value)
  end
end

#expr_query(criterion) ⇒ Selectable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Adds the specified expression to the query.

Criterion must be a hash in one of the following forms:

  • value
  • => value
  • value
  • => operator_value_expression

Field name and operator may be given as either strings or symbols.

Examples:

Create the selection.

selectable.expr_query(age: 50)

Parameters:

  • criterion (Hash) —

    The field/value pairs.

Returns:

Raises:

  • (ArgumentError) 


822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 822

def expr_query(criterion)
  raise ArgumentError, 'Criterion cannot be nil here' if criterion.nil?
  unless criterion.is_a?(Hash)
    raise Errors::InvalidQuery, "Expression must be a Hash: #{Errors::InvalidQuery.truncate_expr(criterion)}"
  end

  # The operator guard is applied by _mongoid_expand_keys, which every
  # query method that accepts a user-supplied expression passes through.
  normalized = _mongoid_expand_keys(criterion)
  clone.tap do |query|
    normalized.each do |field, value|
      field_s = field.to_s
      if field_s.start_with?('$')
        query.add_operator_expression(field_s, value)
      else
        query.add_field_expression(field, value)
      end
    end
    query.reset_strategies!
  end
end

#geo_spatial(criterion) ⇒ Selectable

Note:

The only valid geometry shapes for a $geoIntersects are: :intersects_line, :intersects_point, and :intersects_polygon.

Note:

The only valid options for a $geoWithin query are the geometry shape :within_polygon and the operator :within_box.

Note:

The :within_box operator for the $geoWithin query expects the lower left (south west) coordinate pair as the first argument and the upper right (north east) as the second argument. Important: When latitude and longitude are passed, longitude is expected as the first element of the coordinate pair. Source: https://www.mongodb.com/docs/manual/reference/operator/query/box/

Add a $geoIntersects or $geoWithin selection. Symbol operators must be used as shown in the examples to expand the criteria.

Examples:

Add a geo intersect criterion for a line.

query.geo_spatial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])

Add a geo intersect criterion for a point.

query.geo_spatial(:location.intersects_point => [[ 1, 10 ]])

Add a geo intersect criterion for a polygon.

query.geo_spatial(:location.intersects_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])

Add a geo within criterion for a polygon.

query.geo_spatial(:location.within_polygon => [[ 1, 10 ], [ 2, 10 ], [ 1, 10 ]])

Add a geo within criterion for a box.

query.geo_spatial(:location.within_box => [[ 1, 10 ], [ 2, 10 ])

Parameters:

  • criterion (Hash) —

    The criterion.

Returns:

Raises:



209
210
211
212
213
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 209

def geo_spatial(criterion)
  raise Errors::CriteriaArgumentRequired, :geo_spatial if criterion.nil?

  __merge__(criterion)
end

#gt(criterion) ⇒ Selectable

Add the $gt criterion to the selector.

Examples:

Add the $gt criterion.

selectable.gt(age: 60)

Execute an $gt in a where query.

selectable.where(:field.gt => 10)

Parameters:

  • criterion (Hash) —

    The field/value pairs to check.

Returns:

Raises:



258
259
260
261
262
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 258

def gt(criterion)
  raise Errors::CriteriaArgumentRequired, :gt if criterion.nil?

  and_with_operator(criterion, '$gt')
end

#gte(criterion) ⇒ Selectable

Add the $gte criterion to the selector.

Examples:

Add the $gte criterion.

selectable.gte(age: 60)

Execute an $gte in a where query.

selectable.where(:field.gte => 10)

Parameters:

  • criterion (Hash) —

    The field/value pairs to check.

Returns:

Raises:



276
277
278
279
280
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 276

def gte(criterion)
  raise Errors::CriteriaArgumentRequired, :gte if criterion.nil?

  and_with_operator(criterion, '$gte')
end

#in(condition) ⇒ Selectable Also known as: any_in

Adds the $in selection to the selectable.

Examples:

Add $in selection on an array.

selectable.in(age: [ 1, 2, 3 ])

Add $in selection on a range.

selectable.in(age: 18..24)

Execute an $in in a where query.

selectable.where(:field.in => [ 1, 2, 3 ])

Parameters:

  • condition (Hash) —

    The field/value criterion pairs.

Returns:

Raises:



297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 297

def in(condition)
  raise Errors::CriteriaArgumentRequired, :in if condition.nil?

  condition = expand_condition_to_array_values(condition)

  if strategy
    send(strategy, condition, '$in')
  else
    condition.inject(clone) do |query, (field, value)|
      v = { '$in' => value }
      v = { '$not' => v } if negating?
      query.add_field_expression(field.to_s, v)
    end.reset_strategies!
  end
end

#js_query(criterion) ⇒ Selectable

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Create a javascript selection.

Examples:

Create the javascript selection.

selectable.js_query("this.age == 50")

Parameters:

  • criterion (String) —

    The javascript as a string.

Returns:



854
855
856
857
858
859
860
861
862
863
864
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 854

def js_query(criterion)
  clone.tap do |query|
    if negating?
      query.add_operator_expression('$and',
                                    [ { '$nor' => [ { '$where' => criterion } ] } ])
    else
      query.add_operator_expression('$where', criterion)
    end
    query.reset_strategies!
  end
end

#lt(criterion) ⇒ Selectable

Add the $lt criterion to the selector.

Examples:

Add the $lt criterion.

selectable.lt(age: 60)

Execute an $lt in a where query.

selectable.where(:field.lt => 10)

Parameters:

  • criterion (Hash) —

    The field/value pairs to check.

Returns:

Raises:



326
327
328
329
330
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 326

def lt(criterion)
  raise Errors::CriteriaArgumentRequired, :lt if criterion.nil?

  and_with_operator(criterion, '$lt')
end

#lte(criterion) ⇒ Selectable

Add the $lte criterion to the selector.

Examples:

Add the $lte criterion.

selectable.lte(age: 60)

Execute an $lte in a where query.

selectable.where(:field.lte => 10)

Parameters:

  • criterion (Hash) —

    The field/value pairs to check.

Returns:

Raises:



344
345
346
347
348
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 344

def lte(criterion)
  raise Errors::CriteriaArgumentRequired, :lte if criterion.nil?

  and_with_operator(criterion, '$lte')
end

#max_distance(criterion) ⇒ Selectable

Add a $maxDistance selection to the selectable.

Examples:

Add the $maxDistance selection.

selectable.max_distance(location: 10)

Parameters:

  • criterion (Hash) —

    The field/distance pairs.

Returns:

Raises:



359
360
361
362
363
364
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 359

def max_distance(criterion)
  raise Errors::CriteriaArgumentRequired, :max_distance if criterion.nil?

  # $maxDistance must be given together with $near
  __add__(criterion, '$maxDistance')
end

#mod(criterion) ⇒ Selectable

Adds $mod selection to the selectable.

Examples:

Add the $mod selection.

selectable.mod(field: [ 10, 1 ])

Execute an $mod in a where query.

selectable.where(:field.mod => [ 10, 1 ])

Parameters:

  • criterion (Hash) —

    The field/mod selections.

Returns:

Raises:



377
378
379
380
381
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 377

def mod(criterion)
  raise Errors::CriteriaArgumentRequired, :mod if criterion.nil?

  and_with_operator(criterion, '$mod')
end

#ne(criterion) ⇒ Selectable Also known as: excludes

Adds $ne selection to the selectable.

Examples:

Query for a value $ne to something.

selectable.ne(field: 10)

Execute an $ne in a where query.

selectable.where(:field.ne => "value")

Parameters:

  • criterion (Hash) —

    The field/ne selections.

Returns:

Raises:



395
396
397
398
399
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 395

def ne(criterion)
  raise Errors::CriteriaArgumentRequired, :ne if criterion.nil?

  and_with_operator(criterion, '$ne')
end

#near(criterion) ⇒ Selectable

Adds a $near criterion to a geo selection.

Examples:

Add the $near selection.

selectable.near(location: [ 23.1, 12.1 ])

Execute an $near in a where query.

selectable.where(:field.near => [ 23.2, 12.1 ])

Parameters:

  • criterion (Hash) —

    The field/location pair.

Returns:

Raises:



414
415
416
417
418
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 414

def near(criterion)
  raise Errors::CriteriaArgumentRequired, :near if criterion.nil?

  and_with_operator(criterion, '$near')
end

#near_sphere(criterion) ⇒ Selectable

Adds a $nearSphere criterion to a geo selection.

Examples:

Add the $nearSphere selection.

selectable.near_sphere(location: [ 23.1, 12.1 ])

Execute an $nearSphere in a where query.

selectable.where(:field.near_sphere => [ 10.11, 3.22 ])

Parameters:

  • criterion (Hash) —

    The field/location pair.

Returns:

Raises:



432
433
434
435
436
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 432

def near_sphere(criterion)
  raise Errors::CriteriaArgumentRequired, :near_sphere if criterion.nil?

  and_with_operator(criterion, '$nearSphere')
end

#negating? ⇒ true | false

Is the current selectable negating the next selection?

Examples:

Is the selectable negating?

selectable.negating?

Returns:

  • (true | false) —

    If the selectable is negating.



490
491
492
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 490

def negating?
  !!negating
end

#nin(condition) ⇒ Selectable Also known as: not_in

Adds the $nin selection to the selectable.

Examples:

Add $nin selection on an array.

selectable.nin(age: [ 1, 2, 3 ])

Add $nin selection on a range.

selectable.nin(age: 18..24)

Execute an $nin in a where query.

selectable.where(:field.nin => [ 1, 2, 3 ])

Parameters:

  • condition (Hash) —

    The field/value criterion pairs.

Returns:

Raises:



453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 453

def nin(condition)
  raise Errors::CriteriaArgumentRequired, :nin if condition.nil?

  condition = expand_condition_to_array_values(condition)

  if strategy
    send(strategy, condition, '$nin')
  else
    condition.inject(clone) do |query, (field, value)|
      v = { '$nin' => value }
      v = { '$not' => v } if negating?
      query.add_field_expression(field.to_s, v)
    end.reset_strategies!
  end
end

#none_of(*criteria) ⇒ Selectable

Negate the arguments, constraining the query to only those documents that do NOT match the arguments.

Examples:

Exclude a single criterion.

selectable.none_of(name: /Bob/)

Exclude multiple criteria.

selectable.none_of(name: /Bob/, country: "USA")

Exclude multiple criteria as an array.

selectable.none_of([{ name: /Bob/ }, { country: "USA" }])

Parameters:

  • *criteria ([ Hash | Criteria ]...) —

    The key/value pair matches or Criteria objects to negate.

Returns:



560
561
562
563
564
565
566
567
568
569
570
571
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 560

def none_of(*criteria)
  criteria = _mongoid_flatten_arrays(criteria)
  return dup if criteria.empty?

  exprs = criteria.map do |criterion|
    _mongoid_expand_keys(
      criterion.is_a?(Selectable) ? criterion.selector : criterion
    )
  end

  self.and('$nor' => exprs)
end

#nor(*criteria) ⇒ Selectable

Adds $nor selection to the selectable.

Examples:

Add the $nor selection.

selectable.nor(field: 1, field: 2)

Parameters:

  • *criteria ([ Hash | Criteria | Array<Hash | Criteria> ]...) —

    Multiple key/value pair matches or Criteria objects.

Returns:



480
481
482
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 480

def nor(*criteria)
  _mongoid_add_top_level_operation('$nor', criteria)
end

#not(*criteria) ⇒ Selectable

Negate the arguments.

Examples:

Add the $not criterion.

Person.not(name: /Bob/)

Execute a $not in a where query.

Person.where(:name.not => /Bob/)

Negate a Criteria instance

Person.not(Person.where(...))

Parameters:

  • *criteria ([ Hash | Criteria ]...) —

    The key/value pair matches or Criteria objects to negate.

Returns:



509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 509

def not(*criteria)
  if criteria.empty?
    # @deprecated
    Mongoid.deprecation_warning(
      :not_sans_arguments,
      'Calling `#not` without arguments is deprecated, and will be ' \
      'removed in the next major version. Instead, pass the Hash or ' \
      'Criteria instance to negate.',
      caller_locations
    )
    dup.tap { |query| query.negating = !query.negating }
  else
    criteria.compact.inject(clone) do |c, new_s|
      new_s = new_s.selector if new_s.is_a?(Selectable)
      _mongoid_expand_keys(new_s).each do |k, v|
        k = k.to_s
        if c.selector[k] || k.start_with?('$')
          c = c.send(:__multi__, [ { '$nor' => [ { k => v } ] } ], '$and')
        elsif v.is_a?(Hash)
          c = c.send(:__multi__, [ { '$nor' => [ { k => v } ] } ], '$and')
        else
          negated_operator = if v.is_a?(Regexp)
                               '$not'
                             else
                               '$ne'
                             end
          c = c.send(:__override__, { k => v }, negated_operator)
        end
      end
      c
    end
  end
end

#or(*criteria) ⇒ Selectable

Creates a disjunction using $or from the existing criteria in the receiver and the provided arguments.

This behavior (receiver becoming one of the disjunction operands) matches ActiveRecord's or behavior.

Use any_of to add a disjunction of the arguments as an additional constraint to the criteria already existing in the receiver.

Each argument can be a Hash, a Criteria object, an array of Hash or Criteria objects, or a nested array. Nested arrays will be flattened and can be of any depth. Passing arrays is deprecated.

Examples:

Add the $or selection where both fields must have the specified values.

selectable.or(field: 1, field: 2)

Add the $or selection where either value match is sufficient.

selectable.or({field: 1}, {field: 2})

Same as previous example but using the deprecated array wrap.

selectable.or([{field: 1}, {field: 2}])

Same as previous example, also deprecated.

selectable.or([{field: 1}], [{field: 2}])

Parameters:

  • *criteria ([ Hash | Criteria | Array<Hash | Criteria> ]...) —

    Multiple key/value pair matches or Criteria objects, or arrays thereof. Passing arrays is deprecated.

Returns:



603
604
605
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 603

def or(*criteria)
  _mongoid_add_top_level_operation('$or', criteria)
end

#text_search(terms, opts = nil) ⇒ Selectable

Note:

Per https://www.mongodb.com/docs/manual/reference/operator/query/text/ it is not currently possible to supply multiple text search conditions in a query. Mongoid will build such a query but the server will return an error when trying to execute it.

Construct a text search selector.

Examples:

Construct a text search selector.

selectable.text_search("testing")

Construct a text search selector with options.

selectable.text_search("testing", :$language => "fr")

Parameters:

  • terms (String | Symbol) —

    A string of terms that MongoDB parses and uses to query the text index.

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

    Text search options. See MongoDB documentation for options.

Returns:

Raises:



731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 731

def text_search(terms, opts = nil)
  raise Errors::CriteriaArgumentRequired, :terms if terms.nil?

  clone.tap do |query|
    criterion = { '$text' => { '$search' => terms } }
    criterion['$text'].merge!(opts) if opts
    if query.selector['$text']
      # Per https://www.mongodb.com/docs/manual/reference/operator/query/text/
      # multiple $text expressions are not currently supported by
      # MongoDB server, but build the query correctly instead of
      # overwriting previous text search condition with the currently
      # given one.
      Mongoid.logger.warn('Multiple $text expressions per query are not currently supported by the server')
      query.selector = { '$and' => [ query.selector ] }.merge(criterion)
    else
      query.selector = query.selector.merge(criterion)
    end
  end
end

#where(*criteria) ⇒ Selectable

This is the general entry point for most MongoDB queries. This either creates a standard field: value selection, and expanded selection with the use of hash methods, or a $where selection if a string is provided.

Examples:

Add a standard selection.

selectable.where(name: "syd")

Add a javascript selection.

selectable.where("this.name == 'syd'")

Parameters:

  • *criterion ([ Hash | String ]...) —

    The standard selection or javascript string.

Returns:



765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 765

def where(*criteria)
  return clone.reset_strategies! if criteria.empty?

  criteria.inject(self) do |query, criterion|
    raise Errors::CriteriaArgumentRequired, :where if criterion.nil?

    # We need to save the criterion in an instance variable so
    # Modifiable methods know how to create a polymorphic object.
    # Note that this method in principle accepts multiple criteria,
    # but only the first one will be stored in @criterion. This
    # works out to be fine because first_or_create etc. methods
    # only ever specify one criterion to #where.
    @criterion = criterion
    if criterion.is_a?(String)
      unless Mongoid.allow_unsafe_query_operators?
        raise Errors::InvalidQuery,
              "String criteria are not allowed because they compile to the '$where' operator, " \
              'which is not allowed in a query expression. Set Mongoid.allow_unsafe_query_operators = true ' \
              'to permit all operators.'
      end
      query.js_query(criterion)
    else
      query.expr_query(criterion)
    end
  end
end

#with_size(criterion) ⇒ Selectable

Note:

This method is named #with_size not to conflict with any existing #size method on enumerables or symbols.

Add a $size selection for array fields.

Examples:

Add the $size selection.

selectable.with_size(field: 5)

Execute an $size in a where query.

selectable.where(:field.with_size => 10)

Parameters:

  • criterion (Hash) —

    The field/size pairs criterion.

Returns:

Raises:



677
678
679
680
681
682
683
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 677

def with_size(criterion)
  raise Errors::CriteriaArgumentRequired, :with_size if criterion.nil?

  typed_override(criterion, '$size') do |value|
    ::Integer.evolve(value)
  end
end

#with_type(criterion) ⇒ Selectable

Note:

http://vurl.me/PGOU contains a list of all types.

Adds a $type selection to the selectable.

Examples:

Add the $type selection.

selectable.with_type(field: 15)

Execute an $type in a where query.

selectable.where(:field.with_type => 15)

Parameters:

  • criterion (Hash) —

    The field/type pairs.

Returns:

Raises:



701
702
703
704
705
706
707
 
# File 'lib/mongoid/criteria/queryable/selectable.rb', line 701

def with_type(criterion)
  raise Errors::CriteriaArgumentRequired, :with_type if criterion.nil?

  typed_override(criterion, '$type') do |value|
    ::Integer.evolve(value)
  end
end