instance method has_many

Specifies a one-to-many association. The following methods for retrieval and query of collections of associated objects will be added:

collection is a placeholder for the symbol passed as the name argument, so has_many :clients would add among others clients.empty?.

collection

Returns a Relation of all the associated objects. An empty Relation is returned if none are found.

collection<<(object, …)

Adds one or more objects to the collection by setting their foreign keys to the collection’s primary key. Note that this operation instantly fires update SQL without waiting for the save or update call on the parent object, unless the parent object is a new record. This will also run validations and callbacks of associated object(s).

collection.delete(object, …)

Removes one or more objects from the collection by setting their foreign keys to NULL. Objects will be in addition destroyed if they’re associated with dependent: :destroy, and deleted if they’re associated with dependent: :delete_all.

If the :through option is used, then the join records are deleted (rather than nullified) by default, but you can specify dependent: :destroy or dependent: :nullify to override this.

collection.destroy(object, …)

Removes one or more objects from the collection by running destroy on each record, regardless of any dependent option, ensuring callbacks are run.

If the :through option is used, then the join records are destroyed instead, not the objects themselves.

collection=objects

Replaces the collections content by deleting and adding objects as appropriate. If the :through option is true callbacks in the join models are triggered except destroy callbacks, since deletion is direct by default. You can specify dependent: :destroy or dependent: :nullify to override this.

collection_singular_ids

Returns an array of the associated objects’ ids

collection_singular_ids=ids

Replace the collection with the objects identified by the primary keys in ids. This method loads the models and calls collection=. See above.

collection.clear

Removes every object from the collection. This destroys the associated objects if they are associated with dependent: :destroy, deletes them directly from the database if dependent: :delete_all, otherwise sets their foreign keys to NULL. If the :through option is true no destroy callbacks are invoked on the join models. Join models are directly deleted.

collection.empty?

Returns true if there are no associated objects.

collection.size

Returns the number of associated objects.

collection.find(…)

Finds an associated object according to the same rules as ActiveRecord::FinderMethods#find.

collection.exists?(…)

Checks whether an associated object with the given conditions exists. Uses the same rules as ActiveRecord::FinderMethods#exists?.

collection.build(attributes = {}, …)

Returns one or more new objects of the collection type that have been instantiated with attributes and linked to this object through a foreign key, but have not yet been saved.

collection.create(attributes = {})

Returns a new object of the collection type that has been instantiated with attributes, linked to this object through a foreign key, and that has already been saved (if it passed the validation). Note: This only works if the base model already exists in the DB, not if it is a new (unsaved) record!

collection.create!(attributes = {})

Does the same as collection.create, but raises ActiveRecord::RecordInvalid if the record is invalid.

collection.reload

Returns a Relation of all of the associated objects, forcing a database read. An empty Relation is returned if none are found.

Example

A Firm class declares has_many :clients, which will add:

• Firm#clients (similar to Client.where(firm_id: id))

• Firm#clients<<

• Firm#clients.delete

• Firm#clients.destroy

• Firm#clients=

• Firm#client_ids

• Firm#client_ids=

• Firm#clients.clear

• Firm#clients.empty? (similar to firm.clients.size == 0)

• Firm#clients.size (similar to Client.count "firm_id = #{id}")

• Firm#clients.find (similar to Client.where(firm_id: id).find(id))

• Firm#clients.exists?(name: 'ACME') (similar to Client.exists?(name: 'ACME', firm_id: firm.id))

• Firm#clients.build (similar to Client.new(firm_id: id))

• Firm#clients.create (similar to c = Client.new(firm_id: id); c.save; c)

• Firm#clients.create! (similar to c = Client.new(firm_id: id); c.save!)

• Firm#clients.reload

The declaration can also include an options hash to specialize the behavior of the association.

Scopes

You can pass a second argument scope as a callable (i.e. proc or lambda) to retrieve a specific set of records or customize the generated query when you access the associated collection.

Scope examples:

has_many :comments, -> { where(author_id: 1) }
has_many :employees, -> { joins(:address) }
has_many :posts, ->(blog) { where("max_post_length > ?", blog.max_post_length) }

Extensions

The extension argument allows you to pass a block into a has_many association. This is useful for adding new finders, creators and other factory-type methods to be used as part of the association.

Extension examples:

has_many :employees do
  def find_or_create_by_name(name)
    first_name, last_name = name.split(" ", 2)
    find_or_create_by(first_name: first_name, last_name: last_name)
  end
end

Options

:class_name

Specify the class name of the association. Use it only if that name can’t be inferred from the association name. So has_many :products will by default be linked to the Product class, but if the real class name is SpecialProduct, you’ll have to specify it with this option.

:foreign_key

Specify the foreign key used for the association. By default this is guessed to be the name of this class in lower-case and “_id” suffixed. So a Person class that makes a #has_many association will use “person_id” as the default :foreign_key.

If you are going to modify the association (rather than just read from it), then it is a good idea to set the :inverse_of option.

:foreign_type

Specify the column used to store the associated object’s type, if this is a polymorphic association. By default this is guessed to be the name of the polymorphic association specified on “as” option with a “_type” suffix. So a class that defines a has_many :tags, as: :taggable association will use “taggable_type” as the default :foreign_type.

:primary_key

Specify the name of the column to use as the primary key for the association. By default this is id.

:dependent

Controls what happens to the associated objects when their owner is destroyed. Note that these are implemented as callbacks, and Rails executes callbacks in order. Therefore, other similar callbacks may affect the :dependent behavior, and the :dependent behavior may affect other callbacks.

• :destroy causes all the associated objects to also be destroyed.

• :delete_all causes all the associated objects to be deleted directly from the database (so callbacks will not be executed).

• :nullify causes the foreign keys to be set to NULL. Polymorphic type will also be nullified on polymorphic associations. Callbacks are not executed.

• :restrict_with_exception causes an ActiveRecord::DeleteRestrictionError exception to be raised if there are any associated records.

• :restrict_with_error causes an error to be added to the owner if there are any associated objects.

If using with the :through option, the association on the join model must be a #belongs_to, and the records which get deleted are the join records, rather than the associated records.

If using dependent: :destroy on a scoped association, only the scoped objects are destroyed. For example, if a Post model defines has_many :comments, -> { where published: true }, dependent: :destroy and destroy is called on a post, only published comments are destroyed. This means that any unpublished comments in the database would still contain a foreign key pointing to the now deleted post.

:counter_cache

This option can be used to configure a custom named :counter_cache. You only need this option, when you customized the name of your :counter_cache on the #belongs_to association.

:as

Specifies a polymorphic interface (See #belongs_to).

:through

Specifies an association through which to perform the query. This can be any other type of association, including other :through associations. Options for :class_name, :primary_key and :foreign_key are ignored, as the association uses the source reflection.

If the association on the join model is a #belongs_to, the collection can be modified and the records on the :through model will be automatically created and removed as appropriate. Otherwise, the collection is read-only, so you should manipulate the :through association directly.

If you are going to modify the association (rather than just read from it), then it is a good idea to set the :inverse_of option on the source association on the join model. This allows associated records to be built which will automatically create the appropriate join model records when they are saved. (See the ‘Association Join Models’ section above.)

:source

Specifies the source association name used by #has_many :through queries. Only use it if the name cannot be inferred from the association. has_many :subscribers, through: :subscriptions will look for either :subscribers or :subscriber on Subscription, unless a :source is given.

:source_type

Specifies type of the source association used by #has_many :through queries where the source association is a polymorphic #belongs_to.

:validate

When set to true, validates new objects added to association when saving the parent object. true by default. If you want to ensure associated objects are revalidated on every update, use validates_associated.

:autosave

If true, always save the associated objects or destroy them if marked for destruction, when saving the parent object. If false, never save or destroy the associated objects. By default, only save associated objects that are new records. This option is implemented as a before_save callback. Because callbacks are run in the order they are defined, associated objects may need to be explicitly saved in any user-defined before_save callbacks.

Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets :autosave to true.

:inverse_of

Specifies the name of the #belongs_to association on the associated object that is the inverse of this #has_many association. See ActiveRecord::Associations::ClassMethods’s overview on Bi-directional associations for more detail.

:extend

Specifies a module or array of modules that will be extended into the association object returned. Useful for defining methods on associations, especially when they should be shared between multiple association objects.

Option examples:

has_many :comments, -> { order("posted_on") }
has_many :comments, -> { includes(:author) }
has_many :people, -> { where(deleted: false).order("name") }, class_name: "Person"
has_many :tracks, -> { order("position") }, dependent: :destroy
has_many :comments, dependent: :nullify
has_many :tags, as: :taggable
has_many :reports, -> { readonly }
has_many :subscribers, through: :subscriptions, source: :user