instance method belongs_to

Specifies a one-to-one association with another class. This method should only be used if this class contains the foreign key. If the other class contains the foreign key, then you should use #has_one instead. See Is it a belongs_to or has_one association? for more detail on when to use #has_one and when to use #belongs_to.

Methods will be added for retrieval and query for a single associated object, for which this object holds an id:

association is a placeholder for the symbol passed as the name argument, so belongs_to :author would add among others author.nil?.

association

Returns the associated object. nil is returned if none is found.

association=(associate)

Assigns the associate object, extracts the primary key, and sets it as the foreign key. No modification or deletion of existing records takes place.

build_association(attributes = {})

Returns a new object of the associated type that has been instantiated with attributes and linked to this object through a foreign key, but has not yet been saved.

create_association(attributes = {})

Returns a new object of the associated 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).

create_association!(attributes = {})

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

reload_association

Returns the associated object, forcing a database read.

reset_association

Unloads the associated object. The next access will query it from the database.

association_changed?

Returns true if a new associate object has been assigned and the next save will update the foreign key.

association_previously_changed?

Returns true if the previous save updated the association to reference a new associate object.

Example

class Post < ActiveRecord::Base
  belongs_to :author
end

Declaring belongs_to :author adds the following methods (and more):

post = Post.find(7)
author = Author.find(19)

post.author           # similar to Author.find(post.author_id)
post.author = author  # similar to post.author_id = author.id
post.build_author     # similar to post.author = Author.new
post.create_author    # similar to post.author = Author.new; post.author.save; post.author
post.create_author!   # similar to post.author = Author.new; post.author.save!; post.author
post.reload_author
post.reset_author
post.author_changed?
post.author_previously_changed?

Scopes

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

Scope examples:

belongs_to :firm, -> { where(id: 2) }
belongs_to :user, -> { joins(:friends) }
belongs_to :level, ->(game) { where("game_level > ?", game.current_level) }

Options

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

:class_name

Specify the class name of the association. Use it only if that name can’t be inferred from the association name. So belongs_to :author will by default be linked to the Author class, but if the real class name is Person, 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 the association with an “_id” suffix. So a class that defines a belongs_to :person association will use “person_id” as the default :foreign_key. Similarly, belongs_to :favorite_person, class_name: "Person" will use a foreign key of “favorite_person_id”.

Setting the :foreign_key option prevents automatic detection of the association’s inverse, so it is generally a good idea to set the :inverse_of option as well.

: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 association with a “_type” suffix. So a class that defines a belongs_to :taggable, polymorphic: true association will use “taggable_type” as the default :foreign_type.

:primary_key

Specify the method that returns the primary key of associated object used for the association. By default this is id.

:dependent

If set to :destroy, the associated object is destroyed when this object is. If set to :delete, the associated object is deleted without calling its destroy method. If set to :destroy_async, the associated object is scheduled to be destroyed in a background job. This option should not be specified when #belongs_to is used in conjunction with a #has_many relationship on another class because of the potential to leave orphaned records behind.

:counter_cache

Caches the number of belonging objects on the associate class through the use of CounterCache::ClassMethods#increment_counter and CounterCache::ClassMethods#decrement_counter. The counter cache is incremented when an object of this class is created and decremented when it’s destroyed. This requires that a column named #{table_name}_count (such as comments_count for a belonging Comment class) is used on the associate class (such as a Post class) - that is the migration for #{table_name}_count is created on the associate class (such that Post.comments_count will return the count cached). You can also specify a custom counter cache column by providing a column name instead of a true/false value to this option (e.g., counter_cache: :my_custom_counter.)

Starting to use counter caches on existing large tables can be troublesome, because the column values must be backfilled separately of the column addition (to not lock the table for too long) and before the use of :counter_cache (otherwise methods like size/any?/etc, which use counter caches internally, can produce incorrect results). To safely backfill the values while keeping counter cache columns updated with the child records creation/removal and to avoid the mentioned methods use the possibly incorrect counter cache column values and always get the results from the database, use counter_cache: { active: false }. If you also need to specify a custom column name, use counter_cache: { active: false, column: :my_custom_counter }.

Note: If you’ve enabled the counter cache, then you may want to add the counter cache attribute to the attr_readonly list in the associated classes (e.g. class Post; attr_readonly :comments_count; end).

:polymorphic

Specify this association is a polymorphic association by passing true. Note: Since polymorphic associations rely on storing class names in the database, make sure to update the class names in the *_type polymorphic type column of the corresponding rows.

:validate

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

:autosave

If true, always save the associated object or destroy it if marked for destruction, when saving the parent object. If false, never save or destroy the associated object. By default, only save the associated object if it’s a new record.

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

:touch

If true, the associated object will be touched (the updated_at / updated_on attributes set to current time) when this record is either saved or destroyed. If you specify a symbol, that attribute will be updated with the current time in addition to the updated_at / updated_on attribute. Please note that no validation will be performed when touching, and only the after_touch, after_commit, and after_rollback callbacks will be executed.

:inverse_of

Specifies the name of the #has_one or #has_many association on the associated object that is the inverse of this #belongs_to association. See Bi-directional associations for more detail.

:optional

When set to true, the association will not have its presence validated.

:required

When set to true, the association will also have its presence validated. This will validate the association itself, not the id. You can use :inverse_of to avoid an extra query during validation. NOTE: required is set to true by default and is deprecated. If you don’t want to have association presence validated, use optional: true.

:default

Provide a callable (i.e. proc or lambda) to specify that the association should be initialized with a particular record before validation. Please note that callable won’t be executed if the record exists.

:strict_loading

Enforces strict loading every time the associated record is loaded through this association.

:ensuring_owner_was

Specifies an instance method to be called on the owner. The method must return true in order for the associated records to be deleted in a background job.

:query_constraints

Serves as a composite foreign key. Defines the list of columns to be used to query the associated object. This is an optional option. By default Rails will attempt to derive the value automatically. When the value is set the Array size must match associated model’s primary key or query_constraints size.

Option examples:

belongs_to :firm, foreign_key: "client_of"
belongs_to :person, primary_key: "name", foreign_key: "person_name"
belongs_to :author, class_name: "Person", foreign_key: "author_id"
belongs_to :valid_coupon, ->(o) { where "discounts > ?", o.payments_count },
                          class_name: "Coupon", foreign_key: "coupon_id"
belongs_to :attachable, polymorphic: true
belongs_to :project, -> { readonly }
belongs_to :post, counter_cache: true
belongs_to :comment, touch: true
belongs_to :company, touch: :employees_last_updated_at
belongs_to :user, optional: true
belongs_to :account, default: -> { company.account }
belongs_to :account, strict_loading: true
belongs_to :note, query_constraints: [:organization_id, :note_id]