Module: Origin::Optional

Extended by:
Macroable
Included in:
Queryable
Defined in:
lib/origin/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

- (Object) options

Returns the value of attribute options



10
11
12
# File 'lib/origin/optional.rb', line 10

def options
  @options
end

- (Object) options The query options.(Thequeryoptions.)



10
# File 'lib/origin/optional.rb', line 10

attr_accessor :options

Class Method Details

+ (Array<Symbol>) forwardables

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



351
352
353
# File 'lib/origin/optional.rb', line 351

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

Instance Method Details

- (Optional) ascending(*fields) 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



22
23
24
# File 'lib/origin/optional.rb', line 22

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

- (Optional) batch_size(value = nil)

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



40
41
42
# File 'lib/origin/optional.rb', line 40

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

- (Optional) descending(*fields) 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



54
55
56
# File 'lib/origin/optional.rb', line 54

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

- (Optional) hint(value = nil)

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



71
72
73
# File 'lib/origin/optional.rb', line 71

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

- (Optional) limit(value = nil)

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



85
86
87
88
89
90
91
# File 'lib/origin/optional.rb', line 85

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

- (Optional) max_scan(value = nil)

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



104
105
106
# File 'lib/origin/optional.rb', line 104

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

- (Optional) no_timeout

Tell the query not to timeout.

Examples:

Tell the query not to timeout.

optional.no_timeout

Returns:

Since:

  • 1.0.0



116
117
118
# File 'lib/origin/optional.rb', line 116

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

- (Optional) only(*args)

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



130
131
132
133
134
135
136
137
# File 'lib/origin/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 }}
    )
  end
end

- (Optional) order_by(*spec) 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



170
171
172
173
174
175
176
177
178
179
# File 'lib/origin/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

- (Optional) reorder(*spec)

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



193
194
195
196
# File 'lib/origin/optional.rb', line 193

def reorder(*spec)
  options.delete(:sort)
  order_by(*spec)
end

- (Optional) skip(value = nil) 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



208
209
210
211
212
213
214
# File 'lib/origin/optional.rb', line 208

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

- (Optional) slice(criterion = nil)

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



227
228
229
230
231
232
233
234
235
# File 'lib/origin/optional.rb', line 227

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

- (Optional) snapshot

Tell the query to operate in snapshot mode.

Examples:

Add the snapshot option.

optional.snapshot

Returns:

Since:

  • 1.0.0



245
246
247
248
249
# File 'lib/origin/optional.rb', line 245

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

- (Optional) without(*args)

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



261
262
263
264
265
266
267
268
# File 'lib/origin/optional.rb', line 261

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