Ruby on Rails ActiveRecord Query Interface Scopes


Scopes act as predefined filters on ActiveRecord models.

A scope is defined using the scope class method.

As a simple example, we will use the following model:

class Person < ActiveRecord::Base
  #attribute :first_name, :string
  #attribute :last_name, :string
  #attribute :age, :integer

  # define a scope to get all people under 17
  scope :minors, -> { where(age: 0..17) }

  # define a scope to search a person by last name
  scope :with_last_name, ->(name) { where(last_name: name) }


Scopes can be called directly off the model class:

minors = Person.minors

Scopes can be chained:

peters_children = Person.minors.with_last_name('Peters')

The where method and other query type methods can also be chained:

mary_smith = Person.with_last_name('Smith').where(first_name: 'Mary')

Behind the scenes, scopes are simply syntactic sugar for a standard class method. For example, these methods are functionally identical:

scope :with_last_name, ->(name) { where(name: name) }

# This ^ is the same as this:

def self.with_last_name(name)
  where(name: name)

Default Scope

in your model to set a default scope for all operations on the model.

There is one notable difference between the scope method and a class method: scope-defined scopes will always return an ActiveRecord::Relation, even if the logic within returns nil. Class methods, however, have no such safety net and can break chainability if they return something else.