Public Instance methods
named_scope(name, options = {}, &block)

Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query, such as :conditions => {:color => :red}, :select => ‘shirts.*’, :include => :washing_instructions.

  class Shirt < ActiveRecord::Base
    named_scope :red, :conditions => {:color => 'red'}
    named_scope :dry_clean_only, :joins => :washing_instructions, :conditions => ['washing_instructions.dry_clean_only = ?', true]

The above calls to named_scope define class methods and Shirt.dry_clean_only., in effect, represents the query Shirt.find(:all, :conditions => {:color => ‘red’}).

Unlike Shirt.find(...), however, the object returned by is not an Array; it resembles the association object constructed by a has_many declaration. For instance, you can invoke,,, :conditions => {:size => ‘small’}). Also, just as with the association objects, named \scopes act like an Array, implementing Enumerable;,, and, &block) all behave as if really was an Array.

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

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 will return all of Elton‘s red, dry clean only shirts.

Named \scopes can also be procedural:

  class Shirt < ActiveRecord::Base
    named_scope :colored, lambda { |color|
      { :conditions => { :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
    named_scope :red, :conditions => {:color => 'red'} do
      def dom_id

For testing complex named \scopes, you can examine the scoping options using the proxy_options method on the proxy itself.

  class Shirt < ActiveRecord::Base
    named_scope :colored, lambda { |color|
      { :conditions => { :color => color } }

  expected_options = { :conditions => { :colored => 'red' } }
  assert_equal expected_options, Shirt.colored('red').proxy_options
     # File activerecord/lib/active_record/named_scope.rb, line 86
 86:       def named_scope(name, options = {}, &block)
 87:         name = name.to_sym
 89:         scopes[name] = lambda do |parent_scope, *args|
 90: , case options
 91:             when Hash
 92:               options
 93:             when Proc
 94:               if self.model_name != parent_scope.model_name
 95:                 options.bind(parent_scope).call(*args)
 96:               else
 97:       *args)
 98:               end
 99:           end, &block)
100:         end
102:         singleton_class.send :define_method, name do |*args|
103:           scopes[name].call(self, *args)
104:         end
105:       end
scoped(scope, &block)
    # File activerecord/lib/active_record/named_scope.rb, line 19
19:       def scoped(scope, &block)
20:, scope, &block)
21:       end
    # File activerecord/lib/active_record/named_scope.rb, line 15
15:       def scopes
16:         read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {})
17:       end