Rails Active Record Named Scopes

Active Record Named Scopes

Instance Public methods

with_scope(scope = {}, action = :merge, &block) with_scope lets you apply options to inner block incrementally. It takes a hash and the keys must be :find or :create. :find parameter is Relation while :create parameters are an attributes hash.

class Article < ActiveRecord::Base
  def self.create_with_scope
    with_scope(:find => where(:blog_id => 1), :create => { :blog_id => 1 }) do
      find(1) # => SELECT * from articles WHERE blog_id = 1 AND id = 1
      a = create(1)
      a.blog_id # => 1
    end
  end
end

In nested scopings, all previous parameters are overwritten by the innermost rule, with the exception of where, includes, and joins operations in Relation, which are merged.

joins operations are uniqued so multiple scopes can join in the same table without table aliasing problems. If you need to join multiple tables, but still want one of the tables to be uniqued, use the array of strings format for your joins.

class Article < ActiveRecord::Base
  def self.find_with_scope
    with_scope(:find => where(:blog_id => 1).limit(1), :create => { :blog_id => 1 }) do
      with_scope(:find => limit(10)) do
        all # => SELECT * from articles WHERE blog_id = 1 LIMIT 10
      end
      with_scope(:find => where(:author_id => 3)) do
        all # => SELECT * from articles WHERE blog_id = 1 AND author_id = 3 LIMIT 1
      end
    end
  end
end

You can ignore any previous scopings by using the with_exclusive_scope method.

class Article < ActiveRecord::Base
  def self.find_with_exclusive_scope
    with_scope(:find => where(:blog_id => 1).limit(1)) do
      with_exclusive_scope(:find => limit(10)) do
        all # => SELECT * from articles LIMIT 10
      end
    end
  end
end

Note: the :find scope also has effect on update and deletion methods, like update_all and delete_all.

default_scope

default_scope(scope = {}) Use this macro in your model to set a default scope for all operations on the model.

class Article < ActiveRecord::Base
  default_scope where(:published => true)
end

Article.all # => SELECT * FROM articles WHERE published = true

The default_scope is also applied while creating/building a record. It is not applied while updating a record.

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

You can also use default_scope with a block, in order to have it lazily evaluated:

class Article < ActiveRecord::Base
  default_scope { where(:published_at => Time.now - 1.week) }
end

(You can also pass any object which responds to call to the default_scope macro, and it will be called when building the default scope.)

If you use multiple default_scope declarations in your model then they will be merged together:

class Article < ActiveRecord::Base
  default_scope where(:published => true)
  default_scope where(:rating => 'G')
end

Article.all # => SELECT * FROM articles WHERE published = true AND rating = 'G'

This is also the case with inheritance and module includes where the parent or module defines a default_scope and the child or including class defines a second one.

If you need to do more complex things with a default scope, you can alternatively define it as a class method:

class Article < ActiveRecord::Base
  def self.default_scope
    # Should return a scope, you can call 'super' here etc.
  end
end

activerecord/lib/active_record/scoping/named.rb

scope(name, scope_options = {}) 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’).

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

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

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 ifShirt.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.

On Ruby 1.9 you can use the ‘stabby lambda’ syntax:

scope :colored, ->(color) { where(:color => color) }

Note that scopes defined with scope will be evaluated when they are defined, rather than when they are used. For example, the following would be incorrect:

class Post < ActiveRecord::Base
  scope :recent, where('published_at >= ?', Time.current - 1.week)
end

The example above would be ‘frozen’ to the Time.current value when the Post class was defined, and so the resultant SQL query would always be the same. The correct way to do this would be via a lambda, which will re-evaluate the scope each time it is called:

class Post < ActiveRecord::Base
  scope :recent, lambda { where('published_at >= ?', Time.current - 1.week) }
end

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

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
  end

  def self.titles
    map(&:title)
  end

end

We are able to call the methods like this:

Article.published.featured.latest_article
Article.featured.titles

scoped(options = nil) 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(:color => '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.