### Home Classes Methods

### In Files

- lib/active_record/scoping/named.rb

### Methods

- #scope
- #scoped
- #valid_scope_name?

### Files

- README.rdoc

### Class/Module Index

Quicksearch

- ActiveRecord
- ActiveRecord::ActiveRecordError
- ActiveRecord::AdapterNotFound
- ActiveRecord::AdapterNotSpecified
- ActiveRecord::Aggregations
- ActiveRecord::Aggregations::ClassMethods
- ActiveRecord::AssociationTypeMismatch
- ActiveRecord::Associations
- ActiveRecord::Associations::ClassMethods
- ActiveRecord::AttributeAssignment
- ActiveRecord::AttributeAssignment::ClassMethods
- ActiveRecord::AttributeAssignmentError
- ActiveRecord::AttributeMethods
- ActiveRecord::AttributeMethods::BeforeTypeCast
- ActiveRecord::AttributeMethods::ClassMethods
- ActiveRecord::AttributeMethods::DeprecatedUnderscoreRead
- ActiveRecord::AttributeMethods::DeprecatedUnderscoreRead::ClassMethods
- ActiveRecord::AttributeMethods::Dirty
- ActiveRecord::AttributeMethods::PrimaryKey
- ActiveRecord::AttributeMethods::PrimaryKey::ClassMethods
- ActiveRecord::AttributeMethods::Query
- ActiveRecord::AttributeMethods::Read
- ActiveRecord::AttributeMethods::Read::ClassMethods
- ActiveRecord::AttributeMethods::Serialization
- ActiveRecord::AttributeMethods::Serialization::Attribute
- ActiveRecord::AttributeMethods::Serialization::ClassMethods
- ActiveRecord::AttributeMethods::TimeZoneConversion
- ActiveRecord::AttributeMethods::TimeZoneConversion::ClassMethods
- ActiveRecord::AttributeMethods::Write
- ActiveRecord::AttributeMethods::Write::ClassMethods
- ActiveRecord::AutosaveAssociation
- ActiveRecord::AutosaveAssociation::ClassMethods
- ActiveRecord::Base
- ActiveRecord::Batches
- ActiveRecord::Calculations
- ActiveRecord::Callbacks
- ActiveRecord::Coders
- ActiveRecord::ConfigurationError
- ActiveRecord::ConnectionAdapters
- ActiveRecord::ConnectionAdapters::AbstractAdapter
- ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter
- ActiveRecord::ConnectionAdapters::ConnectionHandler
- ActiveRecord::ConnectionAdapters::ConnectionManagement
- ActiveRecord::ConnectionAdapters::ConnectionPool
- ActiveRecord::ConnectionAdapters::DatabaseLimits
- ActiveRecord::ConnectionAdapters::DatabaseStatements
- ActiveRecord::ConnectionAdapters::Mysql2Adapter
- ActiveRecord::ConnectionAdapters::MysqlAdapter
- ActiveRecord::ConnectionAdapters::MysqlAdapter::StatementPool
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::StatementPool
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::TableDefinition
- ActiveRecord::ConnectionAdapters::PostgreSQLAdapter::Utils
- ActiveRecord::ConnectionAdapters::PostgreSQLColumn
- ActiveRecord::ConnectionAdapters::QueryCache
- ActiveRecord::ConnectionAdapters::Quoting
- ActiveRecord::ConnectionAdapters::SQLiteAdapter
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::ExplainPrettyPrinter
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::StatementPool
- ActiveRecord::ConnectionAdapters::SQLiteAdapter::Version
- ActiveRecord::ConnectionAdapters::SchemaCache
- ActiveRecord::ConnectionAdapters::SchemaStatements
- ActiveRecord::ConnectionAdapters::StatementPool
- ActiveRecord::ConnectionAdapters::Table
- ActiveRecord::ConnectionAdapters::TableDefinition
- ActiveRecord::ConnectionNotEstablished
- ActiveRecord::ConnectionTimeoutError
- ActiveRecord::CounterCache
- ActiveRecord::DangerousAttributeError
- ActiveRecord::Delegation
- ActiveRecord::DynamicFinderMatch
- ActiveRecord::DynamicMatchers
- ActiveRecord::DynamicScopeMatch
- ActiveRecord::Explain
- ActiveRecord::FinderMethods
- ActiveRecord::Fixtures
- ActiveRecord::Fixtures::File
- ActiveRecord::Generators
- ActiveRecord::Generators::Migration
- ActiveRecord::Generators::MigrationGenerator
- ActiveRecord::Generators::ModelGenerator
- ActiveRecord::Generators::ObserverGenerator
- ActiveRecord::Generators::SessionMigrationGenerator
- ActiveRecord::IdentityMap
- ActiveRecord::IdentityMap::Middleware
- ActiveRecord::Inheritance
- ActiveRecord::Inheritance::ClassMethods
- ActiveRecord::Integration
- ActiveRecord::InvalidForeignKey
- ActiveRecord::IrreversibleMigration
- ActiveRecord::Locking
- ActiveRecord::Locking::Optimistic
- ActiveRecord::Locking::Optimistic::ClassMethods
- ActiveRecord::Locking::Pessimistic
- ActiveRecord::LogSubscriber
- ActiveRecord::Migration
- ActiveRecord::Migration::CommandRecorder
- ActiveRecord::MigrationProxy
- ActiveRecord::ModelSchema
- ActiveRecord::ModelSchema::ClassMethods
- ActiveRecord::MultiparameterAssignmentErrors
- ActiveRecord::NestedAttributes
- ActiveRecord::NestedAttributes::ClassMethods
- ActiveRecord::NestedAttributes::TooManyRecords
- ActiveRecord::Observer
- ActiveRecord::Persistence
- ActiveRecord::Persistence::ClassMethods
- ActiveRecord::PreparedStatementInvalid
- ActiveRecord::QueryCache
- ActiveRecord::QueryCache::ClassMethods
- ActiveRecord::QueryMethods
- ActiveRecord::Querying
- ActiveRecord::Railtie
- ActiveRecord::Railties
- ActiveRecord::Railties::ControllerRuntime
- ActiveRecord::Railties::ControllerRuntime::ClassMethods
- ActiveRecord::ReadOnlyRecord
- ActiveRecord::ReadonlyAttributes
- ActiveRecord::ReadonlyAttributes::ClassMethods
- ActiveRecord::RecordInvalid
- ActiveRecord::RecordNotFound
- ActiveRecord::RecordNotSaved
- ActiveRecord::RecordNotUnique
- ActiveRecord::Reflection
- ActiveRecord::Reflection::ClassMethods
- ActiveRecord::Reflection::MacroReflection
- ActiveRecord::Result
- ActiveRecord::Rollback
- ActiveRecord::Sanitization
- ActiveRecord::Sanitization::ClassMethods
- ActiveRecord::Schema
- ActiveRecord::Scoping
- ActiveRecord::Scoping::ClassMethods
- ActiveRecord::Scoping::Default
- ActiveRecord::Scoping::Default::ClassMethods
- ActiveRecord::Scoping::Named
- ActiveRecord::Scoping::Named::ClassMethods
- ActiveRecord::Serialization
- ActiveRecord::SerializationTypeMismatch
- ActiveRecord::SessionStore
- ActiveRecord::SessionStore::Session
- ActiveRecord::SessionStore::SqlBypass
- ActiveRecord::SpawnMethods
- ActiveRecord::StaleObjectError
- ActiveRecord::StatementInvalid
- ActiveRecord::Store
- ActiveRecord::Store::ClassMethods
- ActiveRecord::TestFixtures
- ActiveRecord::TestFixtures::ClassMethods
- ActiveRecord::ThrowResult
- ActiveRecord::Timestamp
- ActiveRecord::Transactions
- ActiveRecord::Transactions::ClassMethods
- ActiveRecord::Translation
- ActiveRecord::UnknownAttributeError
- ActiveRecord::UnknownPrimaryKey
- ActiveRecord::Validations
- ActiveRecord::Validations::AssociatedValidator
- ActiveRecord::Validations::ClassMethods
- ActiveRecord::Validations::UniquenessValidator
- ActiveRecord::WrappedDatabaseException
- Mysql
- Mysql::Result
- Mysql::Stmt
- Mysql::Time
- ArJdbcMySQL
- ArJdbcMySQL::Error

No matching classes.

# ActiveRecord::Scoping::Named::ClassMethods

### Public Instance Methods

scope(name, scope_options = {}) click to toggle source

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

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
        pluck(:title)
      end
    end

We are able to call the methods like this:

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

    # File lib/active_record/scoping/named.rb, line 172
    def scope(name, scope_options = {})
      name = name.to_sym
      valid_scope_name?(name)
      extension = Module.new(&Proc.new) if block_given?

      scope_proc = lambda do |*args|
        options = scope_options.respond_to?(:call) ? unscoped { scope_options.call(*args) } : scope_options
        options = scoped.apply_finder_options(options) if options.is_a?(Hash)

        relation = scoped.merge(options)

        extension ? relation.extending(extension) : relation
      end

      singleton_class.send(:redefine_method, name, &scope_proc)
    end

scoped(options = nil) click to toggle source

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.

    # File lib/active_record/scoping/named.rb, line 30
    def scoped(options = nil)
      if options
        scoped.apply_finder_options(options)
      else
        if current_scope
          current_scope.clone
        else
          scope = relation
          scope.default_scoped = true
          scope
        end
      end
    end

### Protected Instance Methods

valid_scope_name?(name) click to toggle source

    # File lib/active_record/scoping/named.rb, line 191
    def valid_scope_name?(name)
      if logger && respond_to?(name, true)
        logger.warn "Creating scope :#{name}. "                          "Overwriting existing method #{self.name}.#{name}."
      end
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.