# File lib/active_record/named_scope.rb, line 123 def named_scope(*args, &block) ActiveSupport::Deprecation.warn("Base.named_scope has been deprecated, please use Base.scope instead", caller) scope(*args, &block) end
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) end
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')
.
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 => '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
associations. If,
class Person < ActiveRecord::Base has_many :shirts end
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) } end
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 'red_shirts' end end end
Scopes can also be used while creating/building a record.
class Article < ActiveRecord::Base scope :published, where(:published => true) end Article.published.new.published # => true Article.published.create.published # => true
# File lib/active_record/named_scope.rb, line 100 def scope(name, scope_options = {}, &block) name = name.to_sym valid_scope_name?(name) extension = Module.new(&block) if block_given? scopes[name] = lambda do |*args| options = scope_options.is_a?(Proc) ? scope_options.call(*args) : scope_options relation = if options.is_a?(Hash) scoped.apply_finder_options(options) elsif options scoped.merge(options) else scoped end extension ? relation.extending(extension) : relation end singleton_class.send(:redefine_method, name, &scopes[name]) end
Returns an anonymous scope.
posts = Post.scoped posts.size # Fires "select count(*) from posts" and returns the count posts.each {|p| puts p.name } # Fires "select * from posts" and loads post objects fruits = Fruit.scoped fruits = fruits.where(:colour => 'red') if options[:red_only] fruits = fruits.limit(10) if limited?
Anonymous scopes tend to be useful when procedurally generating complex queries, where passing intermediate values (scopes) around as first-class objects is convenient.
You can define a scope that applies to all finders using ActiveRecord::Base.default_scope.
# File lib/active_record/named_scope.rb, line 28 def scoped(options = nil) if options scoped.apply_finder_options(options) else current_scoped_methods ? relation.merge(current_scoped_methods) : relation.clone end end
# File lib/active_record/named_scope.rb, line 36 def scopes read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {}) end
# File lib/active_record/named_scope.rb, line 130 def valid_scope_name?(name) if !scopes[name] && respond_to?(name, true) logger.warn "Creating scope :#{name}. " "Overwriting existing method #{self.name}.#{name}." end end