atomic persistence

Although Mongoid performs atomic operations under the covers by default, there may be cases where you want to do this explicitly without persisting other fields. Mongoid provides support for some of these operations as well.

• Model#add_to_set
• Model#bit
• Model#inc
• Model#pop
• Model#pull
• Model#pull_all
• Model#push
• Model#push_all
• Model#rename
• Model#set
• Model#unset

Model#add_to_set

Performs MongoDB's $addToSet modifier on the supplied field and value. The value will be added to the field if it does not already exist, and if the field is nil it will be initialized to an array with the value in it. If the field is not an array an error will be raised.

person.add_to_set(:aliases, "Bond")

collections["people"].update(
  { "_id" : ... },
  { "$addToSet" : { "aliases" : "Bond" } }
)

Model#bit

Performs MongoDB's $bit modifier on the supplied field and bitwise operations. Note that Ruby 1.8.x hashes are not ordered so the order of application is not guaranteed there.

person.bit(:age, { and: 10, or: 12 })

collections["people"].update(
  { "_id" : ... },
  { "$bit" : { "age" : { "and" : 10, "or" : 12 } } }
)

Model#inc

Performs MongoDB's $inc modifier which increments it's value by the supplied amount or initializes it to that value. If the field is not numeric an error will be raised.

person.inc(:age, 1)

collections["people"].update(
  { "_id" : ... },
  { "$inc" : { "age" : 1 } }
)

Model#pop

Performs MongoDB's $pop modifier that removes the number of elements from the array.

person.pop(:aliases, 1)

collections["people"].update(
  { "_id" : ... },
  { "$pop" : { "aliases" : 1 } }
)

Model#pull

Performs MongoDB's $pull modifier that removes the provided value from the array.

person.pull(:aliases, "Bond")

collections["people"].update(
  { "_id" : ... },
  { "$pull" : { "aliases" : "Bond" } }
)

Model#pull_all

Performs MongoDB's $pullAll modifier that removes all the matching supplied values from the array.

person.pull_all(:aliases, [ "Bond", "James" ])

collections["people"].update(
  { "_id" : ... },
  { "$pullAll" : { "aliases" : [ "Bond", "James" ] } }
)

Model#push

Performs MongoDB's $push modifier that will append the value to the provided field. If the field does not exist it will be initialized as an array with the parameter. If the field exists and is not an array an error will be raised.

person.push(:aliases, "007")

collections["people"].update(
  { "_id" : ... },
  { "$push" : { "aliases" : "007" } }
)

Model#push_all

Performs MongoDB's $pushAll modifier that will append the values to the provided field.

person.push_all(:aliases, [ "007", "008" ])

collections["people"].update(
  { "_id" : ... },
  { "$pushAll" : { "aliases" : [ "007", "008" ] } }
)

Model#rename

Performs MongoDB's $rename modifier that renames a field atomically.

person.rename(:bday, :dob)

collections["people"].update(
  { "_id" : ... },
  { "$rename" : { "bday" : "dob" } }
)

Model#set

Performs MongoDB's $set modifier to atomically set a single value.

person.set(:name, "Tyler Durden")

collections["people"].update(
  { "_id" : ... },
  { "$set" : { "name" : "Tyler Durden" } }
)

Model#unset

Performs MongoDB's $unset modifier to atomically remove a field completely from the database.

person.unset(:name)

collections["people"].update(
  { "_id" : ... },
  { "$unset" : { "name" : 1 } }
)