instance method `default_scope`

Ruby on Rails 7.0.10

Since v3.2.22.5 Private

Available in: v3.2.22.5 v4.0.13 v4.1.16 v4.2.9 v5.2.8.1 v6.0.6 v6.1.7.10 v7.0.10 v7.1.6 v7.2.3 v8.0.4 v8.1.2

Compare with:

default_scope(scope = nil, all_queries: nil, &block)

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 or deleting a record.

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

To apply a #default_scope when updating or deleting a record, add all_queries: true:

class Article < ActiveRecord::Base
  default_scope -> { where(blog_id: 1) }, all_queries: true
end

Applying a default scope to all queries will ensure that records are always queried by the additional conditions. Note that only where clauses apply, as it does not make sense to add order to queries that return a single object by primary key.

Article.find(1).destroy
=> DELETE ... FROM `articles` where ID = 1 AND blog_id = 1;

(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

Parameters

scope opt = nil
all_queries key = nil
block block

Source

# File activerecord/lib/active_record/scoping/default.rb, line 119
          def default_scope(scope = nil, all_queries: nil, &block) # :doc:
            scope = block if block_given?

            if scope.is_a?(Relation) || !scope.respond_to?(:call)
              raise ArgumentError,
                "Support for calling #default_scope without a block is removed. For example instead " \
                "of `default_scope where(color: 'red')`, please use " \
                "`default_scope { where(color: 'red') }`. (Alternatively you can just redefine " \
                "self.default_scope.)"
            end

            default_scope = DefaultScope.new(scope, all_queries)

            self.default_scopes += [default_scope]
          end

Defined in activerecord/lib/active_record/scoping/default.rb line 119 · View on GitHub · Improve this page · Find usages on GitHub

Defined in ActiveRecord::Scoping::Default::ClassMethods

Signature

Parameters