Overview
In this guide, you can learn how how to persist data off of your queries in Mongoid. Mongoid supports persistence operations off of criteria in a limited capacity, allowing you to to expressively perform multi-document insert, update, and delete operations.
To learn more about creating filter criteria, see the Specify a Document Query guide.
To learn more about performing CRUD operations, see the CRUD Operations guide.
Persistence Methods
This section describes methods that you can chain to your queries to create, update, and delete data in your MongoDB collections.
Create a Document
You can use the following methods to create new documents from your query criteria:
create: Saves a model instance to MongoDB- Example:
Band.where(name: 'Daft Punk').create
create!: Saves a model instance to MongoDB or raises an exception if a validation error occurs- Example:
Band.where(name: 'Daft Punk').create!
build: Creates an unsaved model instance- Example:
Band.where(name: 'Daft Punk').build
new: Creates an unsaved model instance- Example:
Band.where(name: 'Daft Punk').new
Update Documents
You can use the following methods to update documents based on your query criteria:
update: Updates attributes of the first matching document- Example:
Band.where(name: 'Sundown').update(label: 'ABC Records')
update_all: Updates attributes of all matching documents- Example:
Band.where(country: 'Canada').update_all(label: 'ABC Records')
add_to_set: Adds a value to a specified array in all matching documents- Example:
Band.where(name: 'Sun Down').add_to_set(label: 'ABC Records')
bit: Performs a bitwise update of a field- Example:
Band.where(name: 'Sun Down').bit(likes: { and: 14, or: 4 })
inc: Increments the value of a field- Example:
Band.where(name: 'Sun Down').inc(likes: 14)
pop: Removes the first or last element of an array field- Example:
Band.where(name: 'Sun Down').pop(members: -1)
pull: Removes all instances of a value or values that match a specified condition from an array field- Example:
Band.where(name: 'Sun Down').pull(members: 'Jonah Larsen')
pull_all: Removes all instances of the specified values from an array field- Example:
Band.where(name: 'Sun Down').pull_all(:members, [ 'Jonah Larsen', 'Dan Jones' ])
push: Appends a specified value to an array field- Example:
Band.where(name: 'Sun Down').push(members: 'Jonah Larsen')
push_all: Appends a specified value by using the$eachoperator in an array field- Example:
Band.where(name: 'Sun Down').push_all(members: [ 'Jonah Larsen', 'Dan Jones' ])
rename: Renames a field in all matching documents- Example:
Band.where(name: 'Sun Down').rename(name: :title)
set: Sets a new value for a specified field in all matching documents- Example:
Band.where(name: 'Sun Down').set(likes: 10000)
unset: Deletes a particular field in all matching documents- Example:
Band.where(name: 'Sun Down').unset(:likes)
Delete Documents
You can use the following methods to delete documents based on your query criteria:
delete: Deletes all matching documents.- Example:
Band.where(label: 'ABC Records').delete
destroy: Deletes all matching documents while running callbacks. This method loads all documents into memory.- Example:
Band.where(label: 'ABC Records').destroy
Additional Information
To learn how to customize your persistence target, see the Persistence Configuration guide.