Class Mongoid::Relations::Referenced::Many
In: lib/mongoid/relations/referenced/many.rb
Parent: Relations::Many

This class defines the behaviour for all relations that are a one-to-many between documents in different collections.

Methods

<<   build   clear   concat   create   create!   delete   delete_all   destroy_all   each   find   new   new   nullify   nullify_all   purge   push   substitute  

Included Modules

Batch

Public Class methods

Instantiate a new references_many relation. Will set the foreign key and the base on the inverse object.

@example Create the new relation.

  Referenced::Many.new(base, target, metadata)

@param [ Document ] base The document this relation hangs off of. @param [ Array<Document> ] target The target of the relation. @param [ Metadata ] metadata The relation‘s metadata.

@since 2.0.0.beta.1

Public Instance methods

Appends a document or array of documents to the relation. Will set the parent and update the index in the process.

@example Append a document.

  person.posts << post

@example Push a document.

  person.posts.push(post)

@example Concat with other documents.

  person.posts.concat([ post_one, post_two ])

@param [ Document, Array<Document> ] *args Any number of documents.

@return [ Array<Document> ] The loaded docs.

@since 2.0.0.beta.1

Build a new document from the attributes and append it to this relation without saving.

@example Build a new document on the relation.

  person.posts.build(:title => "A new post")

@overload build(attributes = {}, options = {}, type = nil)

  @param [ Hash ] attributes The attributes of the new document.
  @param [ Hash ] options The scoped assignment options.
  @param [ Class ] type The optional subclass to build.

@overload build(attributes = {}, type = nil)

  @param [ Hash ] attributes The attributes of the new document.
  @param [ Class ] type The optional subclass to build.

@return [ Document ] The new document.

@since 2.0.0.beta.1

clear()

Alias for purge

concat(*args)

Alias for #<<

Creates a new document on the references many relation. This will save the document if the parent has been persisted.

@example Create and save the new document.

  person.posts.create(:text => "Testing")

@overload create(attributes = nil, options = {}, type = nil)

  @param [ Hash ] attributes The attributes to create with.
  @param [ Hash ] options The scoped assignment options.
  @param [ Class ] type The optional type of document to create.

@overload create(attributes = nil, type = nil)

  @param [ Hash ] attributes The attributes to create with.
  @param [ Class ] type The optional type of document to create.

@return [ Document ] The newly created document.

@since 2.0.0.beta.1

Creates a new document on the references many relation. This will save the document if the parent has been persisted and will raise an error if validation fails.

@example Create and save the new document.

  person.posts.create!(:text => "Testing")

@overload create!(attributes = nil, options = {}, type = nil)

  @param [ Hash ] attributes The attributes to create with.
  @param [ Hash ] options The scoped assignment options.
  @param [ Class ] type The optional type of document to create.

@overload create!(attributes = nil, type = nil)

  @param [ Hash ] attributes The attributes to create with.
  @param [ Class ] type The optional type of document to create.

@raise [ Errors::Validations ] If validation failed.

@return [ Document ] The newly created document.

@since 2.0.0.beta.1

Delete the document from the relation. This will set the foreign key on the document to nil. If the dependent options on the relation are :delete or :destroy the appropriate removal will occur.

@example Delete the document.

  person.posts.delete(post)

@param [ Document ] document The document to remove.

@return [ Document ] The matching document.

@since 2.1.0

Deletes all related documents from the database given the supplied conditions.

@example Delete all documents in the relation.

  person.posts.delete_all

@example Conditonally delete all documents in the relation.

  person.posts.delete_all(:conditions => { :title => "Testing" })

@param [ Hash ] conditions Optional conditions to delete with.

@return [ Integer ] The number of documents deleted.

@since 2.0.0.beta.1

Destroys all related documents from the database given the supplied conditions.

@example Destroy all documents in the relation.

  person.posts.destroy_all

@example Conditonally destroy all documents in the relation.

  person.posts.destroy_all(:conditions => { :title => "Testing" })

@param [ Hash ] conditions Optional conditions to destroy with.

@return [ Integer ] The number of documents destroyd.

@since 2.0.0.beta.1

Iterate over each document in the relation and yield to the provided block.

@note This will load the entire relation into memory.

@example Iterate over the documents.

  person.posts.each do |post|
    post.save
  end

@return [ Array<Document> ] The loaded docs.

@since 2.1.0

Find the matchind document on the association, either based on id or conditions.

@example Find by an id.

  person.posts.find(BSON::ObjectId.new)

@example Find by multiple ids.

  person.posts.find([ BSON::ObjectId.new, BSON::ObjectId.new ])

@example Conditionally find all matching documents.

  person.posts.find(:all, :conditions => { :title => "Sir" })

@example Conditionally find the first document.

  person.posts.find(:first, :conditions => { :title => "Sir" })

@example Conditionally find the last document.

  person.posts.find(:last, :conditions => { :title => "Sir" })

@param [ Symbol, BSON::ObjectId, Array<BSON::ObjectId> ] arg The

  argument to search with.

@param [ Hash ] options The options to search with.

@return [ Document, Criteria ] The matching document(s).

@since 2.0.0.beta.1

new(attributes = {}, options = {}, type = nil)

Alias for build

Removes all associations between the base document and the target documents by deleting the foreign keys and the references, orphaning the target documents in the process.

@example Nullify the relation.

  person.posts.nullify

@since 2.0.0.rc.1

nullify_all()

Alias for nullify

Clear the relation. Will delete the documents from the db if they are already persisted.

@example Clear the relation.

  person.posts.clear

@return [ Many ] The relation emptied.

@since 2.0.0.beta.1

push(*args)

Alias for #<<

Substitutes the supplied target documents for the existing documents in the relation. If the new target is nil, perform the necessary deletion.

@example Replace the relation.

  person.posts.substitute([ new_post ])

@param [ Array<Document> ] replacement The replacement target.

@return [ Many ] The relation.

@since 2.0.0.rc.1

[Validate]