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

#options ⇒ Object

Returns the value of attribute options.



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

def options
  @options
end

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



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

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



322
323
324
 
# File 'lib/origin/optional.rb', line 322

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



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

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



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

def batch_size(value = nil)
  option(value) { |options| options.store(:batch_size, value) }
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



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

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



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

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



85
86
87
 
# File 'lib/origin/optional.rb', line 85

def limit(value = nil)
  option(value) { |options| options.store(:limit, value.to_i) }
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



100
101
102
 
# File 'lib/origin/optional.rb', line 100

def max_scan(value = nil)
  option(value) { |options| options.store(:max_scan, 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



112
113
114
 
# File 'lib/origin/optional.rb', line 112

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



126
127
128
129
130
131
132
 
# File 'lib/origin/optional.rb', line 126

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

#order_by(*spec) ⇒ Optional

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



165
166
167
168
169
170
171
172
173
 
# File 'lib/origin/optional.rb', line 165

def order_by(*spec)
  option(spec) do |options|
    spec.compact.each do |criterion|
      criterion.__sort_option__.each_pair do |field, direction|
        add_sort_option(options, field, direction)
      end
    end
  end
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



185
186
187
 
# File 'lib/origin/optional.rb', line 185

def skip(value = nil)
  option(value) { |options| options.store(:skip, value.to_i) }
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



200
201
202
203
204
205
206
207
208
 
# File 'lib/origin/optional.rb', line 200

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



218
219
220
221
222
 
# File 'lib/origin/optional.rb', line 218

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



234
235
236
237
238
239
240
 
# File 'lib/origin/optional.rb', line 234

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