abstract class Moongoon::Collection::UpdateOnly

Overview

A limited model class for interacting with a MongoDB collection.

NOTE Similar to Moongoon::Collection but can only be used to update a MongoDB collection.

class Partial < Moongoon::Collection::UpdateOnly
  collection "my_models"

  property name : String?
  property age : Int32?
end

Included Modules

Defined in:

models/models.cr

Constructors

Class Method Summary

Instance Method Summary

Macro Summary

Instance methods inherited from class Moongoon::MongoBase

_id : BSON::ObjectId | Nil _id, _id! _id!, _id=(_id : BSON::ObjectId | Nil) _id=, id id, id! id!, id=(id : String) id=, inserted? inserted?, persisted? persisted?, removed? : Bool removed?, unsets_to_bson : BSON | Nil unsets_to_bson

Class methods inherited from class Moongoon::MongoBase

collection : Mongo::Collection collection, database : Mongo::Database database, database_name : String database_name

Instance methods inherited from class Moongoon::Document

to_bson(bson = BSON.new) to_bson, to_tuple to_tuple

Constructor methods inherited from class Moongoon::Document

new(pull : JSON::PullParser)
new(bson : BSON)
new(**args : **T) forall T
new

Class methods inherited from class Moongoon::Document

from_bson(bson : BSON) from_bson

Constructor Detail

def self.new(pull : JSON::PullParser) #

A limited model class for interacting with a MongoDB collection.

NOTE Similar to Moongoon::Collection but can only be used to update a MongoDB collection.

class Partial < Moongoon::Collection::UpdateOnly
  collection "my_models"

  property name : String?
  property age : Int32?
end

[View source]

Class Method Detail

def self.find_and_modify(query, update, fields = @@default_fields, no_hooks = false, **args) #

Modifies and returns a single document.

See the official documentation.

User.find_and_modify({ name: "John" }, { "$set": { "name": "Igor" }})

def self.find_and_modify_by_id(id : BSON::ObjectId | String, update, query = BSON.new, no_hooks = false, **args) #

Modifies and returns a single document.

Similar to self.find_and_modify, except that a matching on the _id field will be added to the query argument.


def self.find_and_remove(query, fields = @@default_fields, no_hooks = false, **args) #

Removes and returns a single document.

See the official documentation.

User.find_and_remove({ name: "John" })

def self.find_and_remove_by_id(id, query = BSON.new, no_hooks = false, **args) #

Removes and returns a single document.

Similar to self.find_and_remove, except that a matching on the _id field will be added to the query argument.


def self.index(keys : NamedTuple, collection : String | Nil = nil, database : String | Nil = nil, options = NamedTuple.new, name : String | Nil = nil) : Nil #

Defines an index that will be applied to this Model's underlying mongo collection.

Note that the order of fields do matter.

If not provided the driver will generate the name of the index from the keys names and order.

Please have a look at the MongoDB documentation for more details about index creation and the list of available index options.

# Specify one or more fields with a type (ascending or descending order, text indexing…)
index keys: { field1: 1, field2: -1 }
# Set the unique argument to create a unique index.
index keys: { field: 1 }, options: { unique: true }

def self.index(keys : Hash(String, BSON::Value), collection : String | Nil = nil, database : String | Nil = nil, options = Hash(String, BSON::Value).new, name : String | Nil = nil) : Nil #

Same as self.index but with hash arguments.

index ({ "a" => 1 }), name: "index_name", options: { "unique" => true }

def self.update(query, update, no_hooks = false, **args) : Mongo::Commands::Common::UpdateResult | Nil #

Updates one or more documents in the underlying collection.

Every document matching the query argument will be updated. See the MongoDB tutorial for more information about the syntax.

# Rename every person named "John" to "Igor".
User.update(query: { name: "John" }, update: { "$set": { name: "Igor" } })

def self.update_by_id(id : BSON::ObjectId | String, update, query = BSON.new, **args) : Mongo::Commands::Common::UpdateResult | Nil #

Updates one document by id.

Similar to self.update, except that a matching on the _id field will be added to the query argument.

id = 123456
User.update_by_id(id, { "$set": { "name": "Igor" }})

It is possible to add query filters to conditionally prevent an update.

# Updates the user only if he/she is named John.
User.update_by_id(id, query: { name: "John" }, update: { "$set": { name: "Igor" }})

def self.update_by_ids(ids, update, query = BSON.new, **args) : Mongo::Commands::Common::UpdateResult | Nil #

Updates one or multiple documents by their ids.

Similar to self.update, except that a matching on multiple _id fields will be added to the query argument.

ids = ["1", "2", "3"]
User.update_by_ids(ids, { "$set": { "name": "Igor" }})

It is possible to add query filters.

# Updates the users only if they are named John.
User.update_by_ids(ids, query: { name: "John" }, update: { "$set": { name: "Igor" }})

Instance Method Detail

def update(query = BSON.new, **args) : self #

Updates a document having the same id as this model with the data stored in self.

Tries to match on self.id.

user = User.new name: "John", age: 25
user.insert
user.age = 26
user.update

It is possible to add query filters to conditionally prevent an update.

user = User.new name: "John", locked: true
user.insert
user.name = "Igor"
# Prevents updating users that are locked.
user.update({ locked: false })
pp User.find_by_id(user.id!).to_json
# => { "id": "some id", "name": "John", "locked": true }

The update can be restricted to specific fields.

user = User.new name: "John", age: 25
user.insert
user.age = 26
user.name = "Tom"
# Updates only the age field.
user.update(fields: {:age})

def update_fields(fields : F, **args) : self forall F #

Update specific fields both in the model and in database.

user = User.new name: "John", age: 25
user.insert
# Updates only the age field.
user.update({age: 26})

def update_query(query, fields = nil, no_hooks = false, **args) : self #

Updates one or more documents with the data stored in self.

Every document matching the query argument will be updated.

user = User.new name: "John", age: 25
user = User.new name: "Jane", age: 30
user.insert
user.age = 40
# Updates both documents
user.update_query({ name: {"$in": ["John", "Jane"]} })

Macro Detail

macro reference(field, *, model, many = false, delete_cascade = false, clear_reference = false, back_reference = nil) #

References one or more documents belonging to another collection.

Creates a model field that will reference either one or multiple foreign documents depending on the arguments provided.

NOTE This macro is useful when using named arguments to keep the reference in sync when documents are added or removed from the other collection.

class MyModel < Moongoon::Collection
  # The following references are not kept in sync because extra named arguments are not used.

  # Reference a single user.
  reference user_id, model: User

  # References multiple users.
  reference user_ids, model: User, many: true

  reference user_ids, model: User, many: true
end

Named arguments

  • model: The referenced model class.
  • many: Set to true to reference multiple documents.
  • delete_cascade: If true, removes the referenced document(s) when this model is removed.
  • clear_reference: If true, sets the reference to nil (if referencing a single document), or removes the id from the reference array (if referencing multiple documents) when the referenced document(s) are removed.
  • back_reference: The name of the refence, if it exists, in the referenced model that back-references this model. If set, when a referenced document gets inserted, this reference will be updated to add the newly created id.
class MyModel < Moongoon::Collection
  # Now some examples that are using extra arguments.

  # References a single user from the User model class.
  # The user has a field that links to back to this model (best_friend_id).
  # Whenever a user is inserted, the reference will get updated to point to the linked user.
  reference user_id, model: User, back_reference: best_friend_id

  # References multiple pets. When this model is removed, all the pets
  # referenced will be removed as well.
  reference pet_ids, model: Pet, many: true, delete_cascade: true

  # Whenever a Pet is removed the reference will get updated and the
  # id of the Pet will be removed from the array.
  reference pet_id, model: Pet, many: true, clear_reference: true
end