Named scope, how do I love thee

I'm not sure how I missed it, but named_scope is something that I've been looking for. I should really read more of Ryan's scraps. Just in case you don't know, named_scope is a way to add filters and conditions to the finder methods on your model.

There's a couple other hipper rails programmers that have covered it months ago, so I'll defer to original author and the aforementioned Ryan and his table scraps to tell you about the basic things you need to know. This functionality has been absorbed into Rails 2.1 and you can find it under the method name, named_scope.

In this post, I'll talk about some of the uses I've found for it. There's more code posting in this one than usual, but it's incremental, so all you have to do is notice what's different between the sets of code examples.

Lately, I've found that I needed to mix and match different kinds of conditions in my finder methods in my models. Let's say we have articles each that have many comments. How do we find comments that have an email address? How about if we wanted articles with a url address included in the comment post? We could make another has_many association.

class Article < ActiveRecord::Base
  has_many :comments, :order => "comments.created_at desc"
  has_many :comments_with_email, 
           :conditions => "email is not null", 
           :order => "comments.created_at desc"
  has_many :comments_with_url, 
           :conditions => "url is not null",
           :order => "comments.created_at desc"
end

class Comment < ActiveRecord::Base
  belongs_to :article
end

Or instead of cluttering things up in the class namespace, we can use an association proxy extension so that instead of calling @article.comments_with_email, we can call @article.comments.with_email (and violate Law of Demeter)

class Article < ActiveRecord::Base
  has_many :comments, :order => "comments.created_at desc" do
    def with_email
      # we can do it this way
      with_scope(:find => { :conditions => "email is not null", 
                            :order => "comments.created_at desc" }) do
        find(:all)
      end
    end

    def with_url
      # or we can do it this way
      find(:all, :conditions => "url is not null", 
                 :order => "comments.created_at desc")
    end
  end
end

class Comment < ActiveRecord::Base
  belongs_to :article
end

This is all fine and well, until you need to find all comments with emails and url. You can make finders that take arguments, but entertain the following possibility. find() in the association proxy extensions actually return an Array, so you cannot chain them, like @article.comments.with_email.with_url

How do we do this? named_scope() is one way to do it.

class Article < ActiveRecord::Base
  has_many :comments. :order => "comments.created_at desc"
end

class Comment < ActiveRecord::Base
  belongs_to :article

  named_scope :with_email, :conditions => "email is not null"
  named_scope :with_url, :conditions => "url is not null"
end

That means you can do things like

@article.comments.with_email

Or you can actually call count(), so that the sql is calling a count instead of instanciating all the active record objects in an array then calling size, which is much faster:

@article.comments.with_email.count

Not only that, but if there are other models that associate with comments, you have the scoping filters in one place in the code.

class User < ActiveRecord::Base
  has_many :comments, :order => "comments.created_at desc"
end

class Article < ActiveRecord::Base
  has_many :comments. :order => "comments.created_at desc"
end

class Comment < ActiveRecord::Base
  belongs_to :article
  belongs_to :user

  named_scope :with_email, :conditions => "email is not null"
  named_scope :with_url, :conditions => "url is not null"
end

So not only can you find all comments with both email and url for an article, you can do the same for users:

@article.comments.with_email.with_url # all comments with email and url of an article
@user.comments.with_email.with_url    # all comments with email and url by a user

Therefore, if you have common intersecting conditions that you need to do, like all the comments in a period of time for an article, named scope will help. For, I'd like to be able to call:

class User < ActiveRecord::Base
  has_many :comments, :order => "comments.created_at desc"
end

class Article < ActiveRecord::Base
  has_many :comments. :order => "comments.created_at desc"
end

class Comment < ActiveRecord::Base
  belongs_to :article
  belongs_to :user

  named_scope :with_email, :conditions => "email is not null"
  named_scope :with_url, :conditions => "url is not null"
  named_scope :in_period, lambda { |start_date, end_date|
    { :conditions => ["respondents.created_at >= ? and " + 
                      "respondents.created_at <= ?", 
                      start_date, end_date] }
  }
end

So now we can call:

  @article.comments.in_period(@start_date, @end_date)
  @article.comments.with_email.in_period(@start_date, @end_date)

Cool you say! Now before you go back into your code and start replacing all of your stuff with named_scopes, keep in mind that there are edge cases where named_scopes wouldn't be appropriate. I fell into the trap of thinking that I could used named_scope for everything like a kid that found a new hammer, the world looked like a nail. So I spend more time than I should trying to bend named_scope to my will.

One of the things that fails is that there is no way (as far as I know) to override named scope conditions, like with_scope, outside of going into rails and messing with it and submitting a patch.

For example, if we already have an association of comments with the article that sorts in descending order, we cannot have named scopes that ask for the earliest and latest article using named_scope.

class Article < ActiveRecord::Base
  has_many :comments. :order => "comments.created_at desc"
end

class Comment < ActiveRecord::Base
  belongs_to :article

  named_scope :earliest, :order => "comments.created_at asc", 
                         :limit => 1
  named_scope :latest, :order => "comments.created_at desc", 
                       :limit => 1
end

This won't work because named_scope assumes that you'd want to merge all the conditions throughout the entire chain.

@article.comments.latest    # will work because the sql will look like:
                            # SELECT * FROM `comments` 
                            # ......blah blah.... 
                            # ORDER BY respondents.created_at desc, 
                            #          respondents.created_at desc 
                            # LIMIT 1

@article.comments.earliest  # will not work because the 
                            # SELECT * FROM `comments` 
                            # ......blah blah.... 
                            # ORDER BY respondents.created_at desc, 
                            #          respondents.created_at asc 
                            # LIMIT 1

Next time, I'll cover named_scopes cousin that's not very documented, so it's easy to skip over: anonymous scopes.

Tip!