Persist Data from Queries
On this page
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 Perform Data 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 MongoDBExample:
Band.where(name: 'Daft Punk').create
create!
: Saves a model instance to MongoDB or raises an exception if a validation error occursExample:
Band.where(name: 'Daft Punk').create!
build
: Creates an unsaved model instanceExample:
Band.where(name: 'Daft Punk').build
new
: Creates an unsaved model instanceExample:
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 documentExample:
Band.where(name: 'Sundown').update(label: 'ABC Records')
update_all
: Updates attributes of all matching documentsExample:
Band.where(country: 'Canada').update_all(label: 'ABC Records')
add_to_set
: Adds a value to a specified array in all matching documentsExample:
Band.where(name: 'Sun Down').add_to_set(label: 'ABC Records')
bit
: Performs a bitwise update of a fieldExample:
Band.where(name: 'Sun Down').bit(likes: { and: 14, or: 4 })
inc
: Increments the value of a fieldExample:
Band.where(name: 'Sun Down').inc(likes: 14)
pop
: Removes the first or last element of an array fieldExample:
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 fieldExample:
Band.where(name: 'Sun Down').pull(members: 'Jonah Larsen')
pull_all
: Removes all instances of the specified values from an array fieldExample:
Band.where(name: 'Sun Down').pull_all(:members, [ 'Jonah Larsen', 'Dan Jones' ])
push
: Appends a specified value to an array fieldExample:
Band.where(name: 'Sun Down').push(members: 'Jonah Larsen')
push_all
: Appends a specified value by using the$each
operator in an array fieldExample:
Band.where(name: 'Sun Down').push_all(members: [ 'Jonah Larsen', 'Dan Jones' ])
rename
: Renames a field in all matching documentsExample:
Band.where(name: 'Sun Down').rename(name: :title)
set
: Sets a new value for a specified field in all matching documentsExample:
Band.where(name: 'Sun Down').set(likes: 10000)
unset
: Deletes a particular field in all matching documentsExample:
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.