Module: Mongoid::Criteria::Queryable::Optional

Extended by:
Macroable
Included in:
Mongoid::Criteria::Queryable
Defined in:
build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb

Overview

The optional module includes all behaviour that has to do with extra options surrounding queries, like skip, limit, sorting, etc.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Macroable

key

Instance Attribute Details

#options ⇒ Object

Returns the value of attribute options.



12
13
14
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 12

def options
  @options
end

#options The query options.(Thequeryoptions.) ⇒ Object 



12
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 12

attr_accessor :options

Class Method Details

.forwardables ⇒ Array<Symbol>

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

Examples:

Get the forwardable methods.

Optional.forwardables

Returns:

  • (Array<Symbol>) —

    The names of the forwardable methods.

Since:

  • 1.0.0



422
423
424
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 422

def forwardables
  public_instance_methods(false) - [ :options, :options= ]
end

Instance Method Details

#ascending(*fields) ⇒ Optional Also known as: asc

Add ascending sorting options for all the provided fields.

Examples:

Add ascending sorting.

optional.ascending(:first_name, :last_name)

Parameters:

  • fields (Array<Symbol>) —

    The fields to sort.

Returns:

Since:

  • 1.0.0



24
25
26
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 24

def ascending(*fields)
  sort_with_list(*fields, 1)
end

#batch_size(value = nil) ⇒ Optional

Adds the option for telling MongoDB how many documents to retrieve in it’s batching.

Examples:

Apply the batch size options.

optional.batch_size(500)

Parameters:

  • value (Integer) (defaults to: nil) —

    The batch size.

Returns:

Since:

  • 1.0.0



42
43
44
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 42

def batch_size(value = nil)
  option(value) { |options| options.store(:batch_size, value) }
end

#collation(collation_doc) ⇒ Optional

Set the collation.

Examples:

Set the collation.

optional.collation(locale: 'fr', strength: 2)

Parameters:

  • collation_doc (Hash) —

    The document describing the collation to use.

Returns:

Since:

  • 6.1.0



337
338
339
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 337

def collation(collation_doc)
  clone.tap { |query| query.options.store(:collation, collation_doc) }
end

#comment(comment = nil) ⇒ Optional

Note:

Set profilingLevel to 2 and the comment will be logged in the profile collection along with the query.

Associate a comment with the query.

Examples:

Add a comment.

optional.comment('slow query')

Parameters:

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

    The comment to be associated with the query.

Returns:

Since:

  • 2.2.0



304
305
306
307
308
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 304

def comment(comment = nil)
  clone.tap do |query|
    query.options.store(:comment, comment)
  end
end

#cursor_type(type) ⇒ Optional

Note:

The cursor can be type :tailable or :tailable_await.

Set the cursor type.

Examples:

Set the cursor type.

optional.cursor_type(:tailable)
optional.cursor_type(:tailable_await)

Parameters:

  • type (Symbol) —

    The type of cursor to create.

Returns:

Since:

  • 2.2.0



323
324
325
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 323

def cursor_type(type)
  clone.tap { |query| query.options.store(:cursor_type, type) }
end

#descending(*fields) ⇒ Optional Also known as: desc

Add descending sorting options for all the provided fields.

Examples:

Add descending sorting.

optional.descending(:first_name, :last_name)

Parameters:

  • fields (Array<Symbol>) —

    The fields to sort.

Returns:

Since:

  • 1.0.0



56
57
58
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 56

def descending(*fields)
  sort_with_list(*fields, -1)
end

#hint(value = nil) ⇒ Optional

Add an index hint to the query options.

Examples:

Add an index hint.

optional.hint("$natural" => 1)

Parameters:

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

    The index hint.

Returns:

Since:

  • 1.0.0



73
74
75
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 73

def hint(value = nil)
  option(value) { |options| options.store(:hint, value) }
end

#limit(value = nil) ⇒ Optional

Add the number of documents to limit in the returned results.

Examples:

Limit the number of returned documents.

optional.limit(20)

Parameters:

  • value (Integer) (defaults to: nil) —

    The number of documents to return.

Returns:

Since:

  • 1.0.0



87
88
89
90
91
92
93
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 87

def limit(value = nil)
  option(value) do |options, query|
    val = value.to_i
    options.store(:limit, val)
    query.pipeline.push("$limit" => val) if aggregating?
  end
end

#max_scan(value = nil) ⇒ Optional

Adds the option to limit the number of documents scanned in the collection.

Examples:

Add the max scan limit.

optional.max_scan(1000)

Parameters:

  • value (Integer) (defaults to: nil) —

    The max number of documents to scan.

Returns:

Since:

  • 1.0.0



106
107
108
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 106

def max_scan(value = nil)
  option(value) { |options| options.store(:max_scan, value) }
end

#max_time_ms(value = nil) ⇒ Optional

Adds a cumulative time limit in milliseconds for processing operations on a cursor.

Examples:

Add the max time ms option.

optional.max_time_ms(200)

Parameters:

  • value (Integer) (defaults to: nil) —

    The max time in milliseconds for processing operations on a cursor.

Returns:

Since:

  • 6.0.0



120
121
122
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 120

def max_time_ms(value = nil)
  option(value) { |options| options.store(:max_time_ms, value) }
end

#no_timeout ⇒ Optional

Tell the query not to timeout.

Examples:

Tell the query not to timeout.

optional.no_timeout

Returns:

Since:

  • 1.0.0



132
133
134
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 132

def no_timeout
  clone.tap { |query| query.options.store(:timeout, false) }
end

#only(*args) ⇒ Optional

Limits the results to only contain the fields provided.

Examples:

Limit the results to the provided fields.

optional.only(:name, :dob)

Parameters:

  • args (Array<Symbol>) —

    The fields to return.

Returns:

Since:

  • 1.0.0



146
147
148
149
150
151
152
153
154
155
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 146

def only(*args)
  args = args.flatten
  option(*args) do |options|
    options.store(
      :fields,
      args.inject(options[:fields] || {}){ |sub, field| sub.tap { sub[field] = 1 }},
      false
    )
  end
end

#order_by(*spec) ⇒ Optional Also known as: order

Adds sorting criterion to the options.

Examples:

Add sorting options via a hash with integer directions.

optional.order_by(name: 1, dob: -1)

Add sorting options via a hash with symbol directions.

optional.order_by(name: :asc, dob: :desc)

Add sorting options via a hash with string directions.

optional.order_by(name: "asc", dob: "desc")

Add sorting options via an array with integer directions.

optional.order_by([[ name, 1 ], [ dob, -1 ]])

Add sorting options via an array with symbol directions.

optional.order_by([[ name, :asc ], [ dob, :desc ]])

Add sorting options via an array with string directions.

optional.order_by([[ name, "asc" ], [ dob, "desc" ]])

Add sorting options with keys.

optional.order_by(:name.asc, :dob.desc)

Add sorting options via a string.

optional.order_by("name ASC, dob DESC")

Parameters:

  • spec (Array, Hash, String) —

    The sorting specification.

Returns:

Since:

  • 1.0.0



188
189
190
191
192
193
194
195
196
197
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 188

def order_by(*spec)
  option(spec) do |options, query|
    spec.compact.each do |criterion|
      criterion.__sort_option__.each_pair do |field, direction|
        add_sort_option(options, field, direction)
      end
      query.pipeline.push("$sort" => options[:sort]) if aggregating?
    end
  end
end

#reorder(*spec) ⇒ Optional

Instead of merging the order criteria, use this method to completely replace the existing ordering with the provided.

Examples:

Replace the ordering.

optional.reorder(name: :asc)

Parameters:

  • spec (Array, Hash, String) —

    The sorting specification.

Returns:

Since:

  • 2.1.0



211
212
213
214
215
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 211

def reorder(*spec)
  clone.tap do |query|
    query.options.delete(:sort)
  end.order_by(*spec)
end

#skip(value = nil) ⇒ Optional Also known as: offset

Add the number of documents to skip.

Examples:

Add the number to skip.

optional.skip(100)

Parameters:

  • value (Integer) (defaults to: nil) —

    The number to skip.

Returns:

Since:

  • 1.0.0



227
228
229
230
231
232
233
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 227

def skip(value = nil)
  option(value) do |options, query|
    val = value.to_i
    options.store(:skip, val)
    query.pipeline.push("$skip" => val) if aggregating?
  end
end

#slice(criterion = nil) ⇒ Optional

Limit the returned results via slicing embedded arrays.

Examples:

Slice the returned results.

optional.slice(aliases: [ 0, 5 ])

Parameters:

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

    The slice options.

Returns:

Since:

  • 1.0.0



246
247
248
249
250
251
252
253
254
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 246

def slice(criterion = nil)
  option(criterion) do |options|
    options.__union__(
      fields: criterion.inject({}) do |option, (field, val)|
        option.tap { |opt| opt.store(field, { "$slice" => val }) }
      end
    )
  end
end

#snapshot ⇒ Optional

Tell the query to operate in snapshot mode.

Examples:

Add the snapshot option.

optional.snapshot

Returns:

Since:

  • 1.0.0



264
265
266
267
268
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 264

def snapshot
  clone.tap do |query|
    query.options.store(:snapshot, true)
  end
end

#without(*args) ⇒ Optional

Limits the results to only contain the fields not provided.

Examples:

Limit the results to the fields not provided.

optional.without(:name, :dob)

Parameters:

  • args (Array<Symbol>) —

    The fields to ignore.

Returns:

Since:

  • 1.0.0



280
281
282
283
284
285
286
287
288
289
 
# File 'build/mongoid-7.0/lib/mongoid/criteria/queryable/optional.rb', line 280

def without(*args)
  args = args.flatten
  option(*args) do |options|
    options.store(
      :fields,
      args.inject(options[:fields] || {}){ |sub, field| sub.tap { sub[field] = 0 }},
      false
    )
  end
end