Ruby on Rails latest stable (v5.2.3) - 1 note - Class: ClassMethods
scope(name, body, &block) public

Adds a class method for retrieving and querying objects. The method is intended to return an ActiveRecord::Relation object, which is composable with other scopes. If it returns nil or false, an {all}[rdoc-ref:Scoping::Named::ClassMethods#all] scope is returned instead.

A scope represents a narrowing of a database query, such as where(color: :red).select('shirts.*').includes(:washing_instructions).

class Shirt < ActiveRecord::Base
  scope :red, -> { where(color: 'red') }
  scope :dry_clean_only, -> { joins(:washing_instructions).where('washing_instructions.dry_clean_only = ?', true) }

The above calls to #scope define class methods Shirt.red and Shirt.dry_clean_only. Shirt.red, in effect, represents the query Shirt.where(color: 'red').

You should always pass a callable object to the scopes defined with #scope. This ensures that the scope is re-evaluated each time it is called.

Note that this is simply ‘syntactic sugar’ for defining an actual class method:

class Shirt < ActiveRecord::Base
  def self.red
    where(color: 'red')

Unlike Shirt.find(...), however, the object returned by Shirt.red is not an Array but an ActiveRecord::Relation, which is composable with other scopes; it resembles the association object constructed by a {has_many}[rdoc-ref:Associations::ClassMethods#has_many] declaration. For instance, you can invoke Shirt.red.first, Shirt.red.count, Shirt.red.where(size: 'small'). Also, just as with the association objects, named scopes act like an Array, implementing Enumerable; Shirt.red.each(&block), Shirt.red.first, and Shirt.red.inject(memo, &block) all behave as if Shirt.red really was an array.

These named scopes are composable. For instance, Shirt.red.dry_clean_only will produce all shirts that are both red and dry clean only. Nested finds and calculations also work with these compositions: Shirt.red.dry_clean_only.count returns the number of garments for which these criteria obtain. Similarly with Shirt.red.dry_clean_only.average(:thread_count).

All scopes are available as class methods on the ActiveRecord::Base descendant upon which the scopes were defined. But they are also available to {has_many}[rdoc-ref:Associations::ClassMethods#has_many] associations. If,

class Person < ActiveRecord::Base
  has_many :shirts

then elton.shirts.red.dry_clean_only will return all of Elton’s red, dry clean only shirts.

Named scopes can also have extensions, just as with {has_many}[rdoc-ref:Associations::ClassMethods#has_many] declarations:

class Shirt < ActiveRecord::Base
  scope :red, -> { where(color: 'red') } do
    def dom_id

Scopes can also be used while creating/building a record.

class Article < ActiveRecord::Base
  scope :published, -> { where(published: true) }

Article.published.new.published    # => true
Article.published.create.published # => true

Class methods on your model are automatically available on scopes. Assuming the following setup:

class Article < ActiveRecord::Base
  scope :published, -> { where(published: true) }
  scope :featured, -> { where(featured: true) }

  def self.latest_article
    order('published_at desc').first

  def self.titles

We are able to call the methods like this:

Show source
Register or log in to add new notes.
October 13, 2015 - (>= v4.1.8)
0 thanks

"Class methods on your model are automatically available on scopes."

The final example above – “Class methods on your model are automatically available on scopes.” – contains a subtle but vital change from earlier versions of the doc – namely, “pluck” (current example) vs “map” (old example). The former works, the latter does not. See http://github.com/rails/rails/issues/21943 for confirmation that the old documentation is incorrect, and for a workaround.

(Spoiler alert: Use


instead of just


in order to achieve the same effect.)