v3.0.0 - Show latest stable - 2 notes - Class: ActiveRecord::NamedScope::ClassMethods
scope(name, scope_options = {}, &block) public

Adds a class method for retrieving and querying objects. 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 =&gt; 'red').

Unlike Shirt.find(...), however, the object returned by Shirt.red is not an Array; it resembles the association object constructed by a has_many declaration. For instance, you can invoke Shirt.red.first, Shirt.red.count, Shirt.red.where(:size =&gt; 'small'). Also, just as with the association objects, named \scopes act like an Array, implementing Enumerable; Shirt.red.each(&amp;block), Shirt.red.first, and Shirt.red.inject(memo, &amp;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 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 be procedural:

  class Shirt < ActiveRecord::Base
    scope :colored, lambda {|color| where(:color => color) }

In this example, Shirt.colored('puce') finds all puce shirts.

Named \scopes can also have extensions, just as with 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
Show source
Register or log in to add new notes.
February 4, 2013
0 thanks

Your scope cannot be called &#x27;locked&#x27;

will cause intermittent problems of the type

undefined method 'locked' for #<Class:0x007fdab3025298>

Use something like ‘access_locked’ instead

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.” – does not work as written. 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.)