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

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `::Mongoid::Criteria`, `::Mongoid::Criteria::Queryable`
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `Macroable`
Defined in:	lib/mongoid/criteria/queryable/optional.rb

Overview

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

Class Method Summary

.forwardables ⇒ Array<Symbol>

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

`Macroable` - Extended

key	Adds a method on `::Symbol` for convenience in where queries for the provided operators.

Instance Attribute Summary

#options rw
#options The query options.(The query options.) rw

Instance Method Summary

#asc(*fields)

Alias for #ascending.
#ascending(*fields) ⇒ Optional (also: #asc)

Add ascending sorting options for all the provided fields.
#batch_size(value = nil) ⇒ Optional

Adds the option for telling MongoDB how many documents to retrieve in it’s batching.
#collation(collation_doc) ⇒ Optional

::Set the collation.
#comment(comment = nil) ⇒ Optional

Associate a comment with the query.
#cursor_type(type) ⇒ Optional

::Set the cursor type.
#desc(*fields)

Alias for #descending.
#descending(*fields) ⇒ Optional (also: #desc)

Add descending sorting options for all the provided fields.
#hint(value = nil) ⇒ Optional

Add an index hint to the query options.
#limit(value = nil) ⇒ Optional

Add the number of documents to limit in the returned results.
#max_scan(value = nil) ⇒ Optional

Adds the option to limit the number of documents scanned in the collection.
#max_time_ms(value = nil) ⇒ Optional

Adds a cumulative time limit in milliseconds for processing operations on a cursor.
#no_timeout ⇒ Optional

Tell the query not to timeout.
#offset(value = nil)

Alias for #skip.
#only(*args) ⇒ Optional

Limits the results to only contain the fields provided.
#order(*spec)

Alias for #order_by.
#order_by(*spec) ⇒ Optional (also: #order)

Adds sorting criterion to the options.
#reorder(*spec) ⇒ Optional

Instead of merging the order criteria, use this method to completely replace the existing ordering with the provided.
#skip(value = nil) ⇒ Optional (also: #offset)

Add the number of documents to skip.
#slice(criterion = nil) ⇒ Optional

Limit the returned results via slicing embedded arrays.
#snapshot ⇒ Optional

Tell the query to operate in snapshot mode.
#without(*args) ⇒ Optional

Limits the results to only contain the fields not provided.
#add_sort_option(options, field, direction) ⇒ Optional private Internal use only Internal use only

Add a single sort option.
#option(*args) ⇒ Queryable private Internal use only Internal use only

Take the provided criterion and store it as an option in the query options.
#sort_with_list(*fields, direction) ⇒ Optional private Internal use only Internal use only

Add multiple sort options at once.

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.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 374


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

Instance Attribute Details

#options (rw)

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 14


attr_accessor :options

#options The query options.(The query options.) (rw)

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 14


attr_accessor :options

Instance Method Details

#add_sort_option(options, field, direction) ⇒ `Optional` (private)

This method is for internal use only.

Add a single sort option.

Examples:

Add a single sort option.

optional.add_sort_option({}, :name, 1)

Parameters:

options (Hash) —

The options.
field (String) —

The field name.
direction (Integer) —

The sort direction.

Returns:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 321


def add_sort_option(options, field, direction)
  sorting = (options[:sort] || {}).dup
  sorting[field] = direction
  options.store(:sort, sorting)
end

#asc(*fields)

Alias for #ascending.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 27


alias :asc :ascending

#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 (Symbol...) —

The field(s) to sort.

Returns:

(Optional) —

The cloned optional.

[ GitHub ]

# File '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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 40


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 303


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 274


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 291


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

#desc(*fields)

Alias for #descending.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 55


alias :desc :descending

#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 (Symbol...) —

The field(s) to sort.

Returns:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 52


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 67


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 79


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 96


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 108


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 118


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

#offset(value = nil)

Alias for #skip.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 212


alias :offset :skip

#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 (Symbol...) —

The field(s) to return.

Returns:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 130


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

#option(*args) ⇒ Queryable (private)

This method is for internal use only.

Take the provided criterion and store it as an option in the query options.

Examples:

Store the option.

optional.option({ skip: 10 })

Parameters:

*args (Object...) —

The options.

Returns:

(Queryable) —

The cloned queryable.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 338


def option(*args)
  clone.tap do |query|
    unless args.compact.empty?
      yield(query.options, query)
    end
  end
end

#order(*spec)

Alias for #order_by.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 180


alias :order :order_by

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

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 170


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 191


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 205


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 222


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:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 238


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

#sort_with_list(*fields, direction) ⇒ `Optional` (private)

This method is for internal use only.

Add multiple sort options at once.

Examples:

Add multiple sort options.

optional.sort_with_list(:name, :dob, 1)

Parameters:

*fields ([ Symbol | String ]...) —

The field name(s).
direction (Integer) —

The sort direction.

Returns:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 357


def sort_with_list(*fields, direction)
  option(fields) do |options, query|
    fields.flatten.compact.each do |field|
      add_sort_option(options, field, direction)
    end
    query.pipeline.push("$sort" => options[:sort]) if aggregating?
  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 (Symbol...) —

The field(s) to ignore.

Returns:

(Optional) —

The cloned optional.

[ GitHub ]

# File 'lib/mongoid/criteria/queryable/optional.rb', line 252


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

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

Overview

Class Method Summary

Macroable - Extended

Instance Attribute Summary

Instance Method Summary

Class Method Details

.forwardables ⇒ Array<Symbol>

Instance Attribute Details

#options (rw)

#options The query options.(The query options.) (rw)

Instance Method Details

#add_sort_option(options, field, direction) ⇒ Optional (private)

#asc(*fields)

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

#batch_size(value = nil) ⇒ Optional

#collation(collation_doc) ⇒ Optional

#comment(comment = nil) ⇒ Optional

#cursor_type(type) ⇒ Optional

#desc(*fields)

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

#hint(value = nil) ⇒ Optional

#limit(value = nil) ⇒ Optional

#max_scan(value = nil) ⇒ Optional

#max_time_ms(value = nil) ⇒ Optional

#no_timeout ⇒ Optional

#offset(value = nil)

#only(*args) ⇒ Optional

#option(*args) ⇒ Queryable (private)

#order(*spec)

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

#reorder(*spec) ⇒ Optional

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

#slice(criterion = nil) ⇒ Optional

#snapshot ⇒ Optional

#sort_with_list(*fields, direction) ⇒ Optional (private)

#without(*args) ⇒ Optional

`Macroable` - Extended

#add_sort_option(options, field, direction) ⇒ `Optional` (private)

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

#batch_size(value = nil) ⇒ `Optional`

#collation(collation_doc) ⇒ `Optional`

#comment(comment = nil) ⇒ `Optional`

#cursor_type(type) ⇒ `Optional`

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

#hint(value = nil) ⇒ `Optional`

#limit(value = nil) ⇒ `Optional`

#max_scan(value = nil) ⇒ `Optional`

#max_time_ms(value = nil) ⇒ `Optional`

#no_timeout ⇒ `Optional`

#only(*args) ⇒ `Optional`

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

#reorder(*spec) ⇒ `Optional`

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

#slice(criterion = nil) ⇒ `Optional`

#snapshot ⇒ `Optional`

#sort_with_list(*fields, direction) ⇒ `Optional` (private)

#without(*args) ⇒ `Optional`