Module: Mongoid::Contextual::Atomic

Relationships & Source Files
Defined in:	lib/mongoid/contextual/atomic.rb

Overview

Mixin module included in ::Mongoid::Criteria which provides a direct method interface to MongoDB’s Update Operators ($set, $pull, $inc, etc.) These operators can be applied to update all documents in the database within the criteria scope, without loading each document into Mongoid’s memory.

Instance Method Summary

#add_each_to_set(adds) ⇒ nil

Perform an atomic $addToSet/$each on the matching documents.
#add_to_set(adds) ⇒ nil

Execute an atomic $addToSet on the matching documents.
#bit(bits) ⇒ nil

Perform an atomic $bit operation on the matching documents.
#clamp_lower_bound(fields)

Alias for #set_max.
#clamp_upper_bound(fields)

Alias for #set_min.
#inc(incs) ⇒ nil

Perform an atomic $inc operation on the matching documents.
#mul(factors) ⇒ nil

Perform an atomic $mul operation on the matching documents.
#pop(pops) ⇒ nil

Perform an atomic $pop operation on the matching documents.
#pull(pulls) ⇒ nil

Perform an atomic $pull operation on the matching documents.
#pull_all(pulls) ⇒ nil

Perform an atomic $pullAll operation on the matching documents.
#push(pushes) ⇒ nil

Perform an atomic $push operation on the matching documents.
#push_all(pushes) ⇒ nil

Perform an atomic $push/$each operation on the matching documents.
#rename(renames) ⇒ nil

Perform an atomic $rename of fields on the matching documents.
#set(sets) ⇒ nil

Perform an atomic $set of fields on the matching documents.
#set_max(fields) ⇒ nil (also: #clamp_lower_bound)

Performs an atomic $max update operation on the given field or fields.
#set_min(fields) ⇒ nil (also: #clamp_upper_bound)

Performs an atomic $min update operation on the given field or fields.
#unset(*unsets) ⇒ nil

Perform an atomic $unset of a field on the matching documents.
#collect_each_operations(ops) private
#collect_operations(ops, aggregator = {}) ⇒ Hash private

Collects and aggregates operations by field.
#collect_unset_operations(ops) ⇒ Hash private

Builds the selector an atomic $unset operation from arguments.

Instance Method Details

#add_each_to_set(adds) ⇒ `nil`

Perform an atomic $addToSet/$each on the matching documents.

Examples:

Add the value to the set.

context.add_each_to_set(members: ["Dave", "Bill"], genres: ["Electro", "Disco"])

Parameters:

adds (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 34


def add_each_to_set(adds)
  view.update_many("$addToSet" => collect_each_operations(adds))
end

#add_to_set(adds) ⇒ `nil`

Execute an atomic $addToSet on the matching documents.

Examples:

Add the value to the set.

context.add_to_set(members: "Dave", genres: "Electro")

Parameters:

adds (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 22


def add_to_set(adds)
  view.update_many("$addToSet" => collect_operations(adds))
end

#bit(bits) ⇒ `nil`

Perform an atomic $bit operation on the matching documents.

Examples:

Perform the bitwise op.

context.bit(likes: { and: 14, or: 4 })

Parameters:

bits (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 46


def bit(bits)
  view.update_many("$bit" => collect_operations(bits))
end

#clamp_lower_bound(fields)

Alias for #set_max.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 226


alias :clamp_lower_bound :set_max

#clamp_upper_bound(fields)

Alias for #set_min.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 203


alias :clamp_upper_bound :set_min

#collect_each_operations(ops) (private)

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 242


def collect_each_operations(ops)
  ops.each_with_object({}) do |(field, value), operations|
    operations[database_field_name(field)] = { "$each" => Array.wrap(value).mongoize }
  end
end

#collect_operations(ops, aggregator = {}) ⇒ Hash (private)

Collects and aggregates operations by field.

Parameters:

ops (Array | Hash) —

The operations to collect.
aggregator (Hash) (defaults to: {}) —

The hash to use to aggregate the operations.

Returns:

(Hash) —

The aggregated operations, by field.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 236


def collect_operations(ops, aggregator = {})
  ops.each_with_object(aggregator) do |(field, value), operations|
    operations[database_field_name(field)] = value.mongoize
  end
end

#collect_unset_operations(ops) ⇒ Hash (private)

Builds the selector an atomic $unset operation from arguments.

Examples:

Prepare selector from array.

context.collect_unset_operations([:name, :age])
#=> { "name" => true, "age" => true }

Prepare selector from hash.

context.collect_unset_operations({ name: 1 }, { age: 1 })
#=> { "name" => true, "age" => true }

Parameters:

ops (String | Symbol | Array<String | Symbol> | Hash) —

The name(s) of the field(s) to unset.

Returns:

(Hash) —

The selector for the atomic $unset operation.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 262


def collect_unset_operations(ops)
  ops.map { |op| op.is_a?(Hash) ? op.keys : op }.flatten
     .map { |field| [database_field_name(field), true] }.to_h
end

#inc(incs) ⇒ `nil`

Perform an atomic $inc operation on the matching documents.

Examples:

Perform the atomic increment.

context.inc(likes: 10)

Parameters:

incs (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 58


def inc(incs)
  view.update_many("$inc" => collect_operations(incs))
end

#mul(factors) ⇒ `nil`

Perform an atomic $mul operation on the matching documents.

Examples:

Perform the atomic multiplication.

context.mul(likes: 10)

Parameters:

factors (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 70


def mul(factors)
  view.update_many("$mul" => collect_operations(factors))
end

#pop(pops) ⇒ `nil`

Perform an atomic $pop operation on the matching documents.

Examples:

Pop the first value on the matches.

context.pop(members: -1)

Pop the last value on the matches.

context.pop(members: 1)

Parameters:

pops (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 85


def pop(pops)
  view.update_many("$pop" => collect_operations(pops))
end

#pull(pulls) ⇒ `nil`

Note:

Expression pulling is not yet supported.

Perform an atomic $pull operation on the matching documents.

Examples:

Pull the value from the matches.

context.pull(members: "Dave")

Parameters:

pulls (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 99


def pull(pulls)
  view.update_many("$pull" => collect_operations(pulls))
end

#pull_all(pulls) ⇒ `nil`

Perform an atomic $pullAll operation on the matching documents.

Examples:

Pull all the matching values from the matches.

context.pull_all(:members, [ "Alan", "Vince" ])

Parameters:

pulls (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 111


def pull_all(pulls)
  view.update_many("$pullAll" => collect_operations(pulls))
end

#push(pushes) ⇒ `nil`

Perform an atomic $push operation on the matching documents.

Examples:

Push the value to the matching docs.

context.push(members: "Alan")

Parameters:

pushes (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 123


def push(pushes)
  view.update_many("$push" => collect_operations(pushes))
end

#push_all(pushes) ⇒ `nil`

Perform an atomic $push/$each operation on the matching documents.

Examples:

Push the values to the matching docs.

context.push_all(members: [ "Alan", "Fletch" ])

Parameters:

pushes (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 135


def push_all(pushes)
  view.update_many("$push" => collect_each_operations(pushes))
end

#rename(renames) ⇒ `nil`

Perform an atomic $rename of fields on the matching documents.

Examples:

Rename the fields on the matching documents.

context.rename(members: :artists)

Parameters:

renames (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 147


def rename(renames)
  operations = renames.inject({}) do |ops, (old_name, new_name)|
    ops[old_name] = new_name.to_s
    ops
  end
  view.update_many("$rename" => collect_operations(operations))
end

#set(sets) ⇒ `nil`

Perform an atomic $set of fields on the matching documents.

Examples:

::Set the field value on the matches.

context.set(name: "Depeche Mode")

Parameters:

sets (Hash) —

The operations.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 163


def set(sets)
  view.update_many("$set" => collect_operations(sets))
end

#set_max(fields) ⇒ `nil` Also known as: #clamp_lower_bound

Note:

Because of the existence of Mongoid::Contextual::Aggregable::Mongo#max, this method cannot be named #max, and thus breaks that convention of other similar methods of being named for the MongoDB operation they perform.

Performs an atomic $max update operation on the given field or fields. Each field will be set to the maximum of [current_value, given value]. This has the effect of making sure that each field is no smaller than the given value; in other words, the given value is the effective minimum for that field.

Examples:

::Set “views” to be no less than 100.

context.set_max(views: 100)

Parameters:

fields (Hash) —

The fields with the minimum value that each may be set to.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 223


def set_max(fields)
  view.update_many("$max" => collect_operations(fields))
end

#set_min(fields) ⇒ `nil` Also known as: #clamp_upper_bound

Note:

Because of the existence of Mongoid::Contextual::Aggregable::Mongo#min, this method cannot be named #min, and thus breaks that convention of other similar methods of being named for the MongoDB operation they perform.

Performs an atomic $min update operation on the given field or fields. Each field will be set to the minimum of [current_value, given value]. This has the effect of making sure that each field is no larger than the given value; in other words, the given value is the effective maximum for that field.

Examples:

::Set “views” to be no more than 100.

context.set_min(views: 100)

Parameters:

fields (Hash) —

The fields with the maximum value that each may be set to.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 200


def set_min(fields)
  view.update_many("$min" => collect_operations(fields))
end

#unset(*unsets) ⇒ `nil`

Perform an atomic $unset of a field on the matching documents.

Examples:

Unset the field on the matches.

context.unset(:name)

Parameters:

*unsets ([ String | Symbol | Array<String | Symbol> | Hash ]...) —

The name(s) of the field(s) to unset. If a ::Hash is specified, its keys will be used irrespective of value, even if the value is nil or false.

Returns:

(nil) —

Nil.

[ GitHub ]

# File 'lib/mongoid/contextual/atomic.rb', line 178


def unset(*unsets)
  view.update_many('$unset' => collect_unset_operations(unsets))
end

Module: Mongoid::Contextual::Atomic

Overview

Instance Method Summary

Instance Method Details

#add_each_to_set(adds) ⇒ nil

#add_to_set(adds) ⇒ nil

#bit(bits) ⇒ nil

#clamp_lower_bound(fields)

#clamp_upper_bound(fields)

#collect_each_operations(ops) (private)

#collect_operations(ops, aggregator = {}) ⇒ Hash (private)

#collect_unset_operations(ops) ⇒ Hash (private)

#inc(incs) ⇒ nil

#mul(factors) ⇒ nil

#pop(pops) ⇒ nil

#pull(pulls) ⇒ nil

#pull_all(pulls) ⇒ nil

#push(pushes) ⇒ nil

#push_all(pushes) ⇒ nil

#rename(renames) ⇒ nil

#set(sets) ⇒ nil

#set_max(fields) ⇒ nil Also known as: #clamp_lower_bound

#set_min(fields) ⇒ nil Also known as: #clamp_upper_bound

#unset(*unsets) ⇒ nil

#add_each_to_set(adds) ⇒ `nil`

#add_to_set(adds) ⇒ `nil`

#bit(bits) ⇒ `nil`

#inc(incs) ⇒ `nil`

#mul(factors) ⇒ `nil`

#pop(pops) ⇒ `nil`

#pull(pulls) ⇒ `nil`

#pull_all(pulls) ⇒ `nil`

#push(pushes) ⇒ `nil`

#push_all(pushes) ⇒ `nil`

#rename(renames) ⇒ `nil`

#set(sets) ⇒ `nil`

#set_max(fields) ⇒ `nil` Also known as: #clamp_lower_bound

#set_min(fields) ⇒ `nil` Also known as: #clamp_upper_bound

#unset(*unsets) ⇒ `nil`