Module: ActiveRecord::QueryMethods

Extended by:
ActiveSupport::Concern
Includes:
ActiveModel::ForbiddenAttributesProtection
Included in:
Relation
Defined in:
activerecord/lib/active_record/relation/query_methods.rb

Defined Under Namespace

Classes: WhereChain

Constant Summary

VALID_UNSCOPING_VALUES =
Set.new([:where, :select, :group, :order, :lock,
:limit, :offset, :joins, :includes, :from,
:readonly, :having])

Instance Method Summary collapse

Methods included from ActiveSupport::Concern

append_features, class_methods, extended, included

Instance Method Details

#_select!(*fields) ⇒ Object

:nodoc:



253
254
255
256
257
258
259
260
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 253

def _select!(*fields) # :nodoc:
  fields.flatten!
  fields.map! do |field|
    klass.attribute_alias?(field) ? klass.attribute_alias(field) : field
  end
  self.select_values += fields
  self
end

#arelObject

Returns the Arel object associated with the relation.



870
871
872
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 870

def arel # :nodoc:
  @arel ||= build_arel
end

#bound_attributesObject



96
97
98
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 96

def bound_attributes
  from_clause.binds + arel.bind_values + where_clause.binds + having_clause.binds
end

#create_with(value) ⇒ Object

Sets attributes to be used when creating new records from a relation object.

users = User.where(name: 'Oscar')
users.new.name # => 'Oscar'

users = users.create_with(name: 'DHH')
users.new.name # => 'DHH'

You can pass nil to create_with to reset attributes:

users = users.create_with(nil)
users.new.name # => 'Oscar'


742
743
744
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 742

def create_with(value)
  spawn.create_with!(value)
end

#create_with!(value) ⇒ Object

:nodoc:



746
747
748
749
750
751
752
753
754
755
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 746

def create_with!(value) # :nodoc:
  if value
    value = sanitize_forbidden_attributes(value)
    self.create_with_value = create_with_value.merge(value)
  else
    self.create_with_value = {}
  end

  self
end

#create_with_valueObject

:nodoc:



100
101
102
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 100

def create_with_value # :nodoc:
  @values[:create_with] || {}
end

#distinct(value = true) ⇒ Object Also known as: uniq

Specifies whether the records should be unique or not. For example:

User.select(:name)
# => Might return two records with the same name

User.select(:name).distinct
# => Returns 1 record per distinct name

User.select(:name).distinct.distinct(false)
# => You can also remove the uniqueness


789
790
791
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 789

def distinct(value = true)
  spawn.distinct!(value)
end

#distinct!(value = true) ⇒ Object Also known as: uniq!

Like #distinct, but modifies relation in place.



795
796
797
798
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 795

def distinct!(value = true) # :nodoc:
  self.distinct_value = value
  self
end

#eager_load(*args) ⇒ Object

Forces eager loading by performing a LEFT OUTER JOIN on args:

User.eager_load(:posts)
=> SELECT "users"."id" AS t0_r0, "users"."name" AS t0_r1, ...
FROM "users" LEFT OUTER JOIN "posts" ON "posts"."user_id" =
"users"."id"


158
159
160
161
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 158

def eager_load(*args)
  check_if_method_has_arguments!(:eager_load, args)
  spawn.eager_load!(*args)
end

#eager_load!(*args) ⇒ Object

:nodoc:



163
164
165
166
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 163

def eager_load!(*args) # :nodoc:
  self.eager_load_values += args
  self
end

#extending(*modules, &block) ⇒ Object

Used to extend a scope with additional methods, either through a module or through a block provided.

The object returned is a relation, which can be further extended.

Using a module

module Pagination
  def page(number)
    # pagination code goes here
  end
end

scope = Model.all.extending(Pagination)
scope.page(params[:page])

You can also pass a list of modules:

scope = Model.all.extending(Pagination, SomethingElse)

Using a block

scope = Model.all.extending do
  def page(number)
    # pagination code goes here
  end
end
scope.page(params[:page])

You can also use a block and a module list:

scope = Model.all.extending(Pagination) do
  def per_page(number)
    # pagination code goes here
  end
end


837
838
839
840
841
842
843
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 837

def extending(*modules, &block)
  if modules.any? || block
    spawn.extending!(*modules, &block)
  else
    self
  end
end

#extending!(*modules, &block) ⇒ Object

:nodoc:



845
846
847
848
849
850
851
852
853
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 845

def extending!(*modules, &block) # :nodoc:
  modules << Module.new(&block) if block
  modules.flatten!

  self.extending_values += modules
  extend(*extending_values) if extending_values.any?

  self
end

#from(value, subquery_name = nil) ⇒ Object

Specifies table from which the records will be fetched. For example:

Topic.select('title').from('posts')
# => SELECT title FROM posts

Can accept other relation objects. For example:

Topic.select('title').from(Topic.approved)
# => SELECT title FROM (SELECT * FROM topics WHERE approved = 't') subquery

Topic.select('a.title').from(Topic.approved, :a)
# => SELECT a.title FROM (SELECT * FROM topics WHERE approved = 't') a


770
771
772
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 770

def from(value, subquery_name = nil)
  spawn.from!(value, subquery_name)
end

#from!(value, subquery_name = nil) ⇒ Object

:nodoc:



774
775
776
777
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 774

def from!(value, subquery_name = nil) # :nodoc:
  self.from_clause = Relation::FromClause.new(value, subquery_name)
  self
end

#group(*args) ⇒ Object

Allows to specify a group attribute:

User.group(:name)
=> SELECT "users".* FROM "users" GROUP BY name

Returns an array with distinct records based on the group attribute:

User.select([:id, :name])
=> [#<User id: 1, name: "Oscar">, #<User id: 2, name: "Oscar">, #<User id: 3, name: "Foo">

User.group(:name)
=> [#<User id: 3, name: "Foo", ...>, #<User id: 2, name: "Oscar", ...>]

User.group('name AS grouped_name, age')
=> [#<User id: 3, name: "Foo", age: 21, ...>, #<User id: 2, name: "Oscar", age: 21, ...>, #<User id: 5, name: "Foo", age: 23, ...>]

Passing in an array of attributes to group by is also supported.

User.select([:id, :first_name]).group(:id, :first_name).first(3)
=> [#<User id: 1, first_name: "Bill">, #<User id: 2, first_name: "Earl">, #<User id: 3, first_name: "Beto">]


281
282
283
284
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 281

def group(*args)
  check_if_method_has_arguments!(:group, args)
  spawn.group!(*args)
end

#group!(*args) ⇒ Object

:nodoc:



286
287
288
289
290
291
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 286

def group!(*args) # :nodoc:
  args.flatten!

  self.group_values += args
  self
end

#having(opts, *rest) ⇒ Object

Allows to specify a HAVING clause. Note that you can't use HAVING without also specifying a GROUP clause.

Order.having('SUM(price) > 30').group('user_id')


620
621
622
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 620

def having(opts, *rest)
  opts.blank? ? self : spawn.having!(opts, *rest)
end

#having!(opts, *rest) ⇒ Object

:nodoc:



624
625
626
627
628
629
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 624

def having!(opts, *rest) # :nodoc:
  references!(PredicateBuilder.references(opts)) if Hash === opts

  self.having_clause += having_clause_factory.build(opts, rest)
  self
end

#includes(*args) ⇒ Object

Specify relationships to be included in the result set. For example:

users = User.includes(:address)
users.each do |user|
  user.address.city
end

allows you to access the address attribute of the User model without firing an additional query. This will often result in a performance improvement over a simple join.

You can also specify multiple relationships, like this:

users = User.includes(:address, :friends)

Loading nested relationships is possible using a Hash:

users = User.includes(:address, friends: [:address, :followers])

conditions

If you want to add conditions to your included models you'll have to explicitly reference them. For example:

User.includes(:posts).where('posts.name = ?', 'example')

Will throw an error, but this will work:

User.includes(:posts).where('posts.name = ?', 'example').references(:posts)

Note that includes works with association names while references needs the actual table name.



139
140
141
142
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 139

def includes(*args)
  check_if_method_has_arguments!(:includes, args)
  spawn.includes!(*args)
end

#includes!(*args) ⇒ Object

:nodoc:



144
145
146
147
148
149
150
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 144

def includes!(*args) # :nodoc:
  args.reject!(&:blank?)
  args.flatten!

  self.includes_values |= args
  self
end

#joins(*args) ⇒ Object

Performs a joins on args:

User.joins(:posts)
=> SELECT "users".* FROM "users" INNER JOIN "posts" ON "posts"."user_id" = "users"."id"

You can use strings in order to customize your joins:

User.joins("LEFT JOIN bookmarks ON bookmarks.bookmarkable_type = 'Post' AND bookmarks.user_id = users.id")
=> SELECT "users".* FROM "users" LEFT JOIN bookmarks ON bookmarks.bookmarkable_type = 'Post' AND bookmarks.user_id = users.id


422
423
424
425
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 422

def joins(*args)
  check_if_method_has_arguments!(:joins, args)
  spawn.joins!(*args)
end

#joins!(*args) ⇒ Object

:nodoc:



427
428
429
430
431
432
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 427

def joins!(*args) # :nodoc:
  args.compact!
  args.flatten!
  self.joins_values += args
  self
end

#limit(value) ⇒ Object

Specifies a limit for the number of records to retrieve.

User.limit(10) # generated SQL has 'LIMIT 10'

User.limit(10).limit(20) # generated SQL has 'LIMIT 20'


636
637
638
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 636

def limit(value)
  spawn.limit!(value)
end

#limit!(value) ⇒ Object

:nodoc:



640
641
642
643
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 640

def limit!(value) # :nodoc:
  self.limit_value = value
  self
end

#lock(locks = true) ⇒ Object

Specifies locking settings (default to true). For more information on locking, please see ActiveRecord::Locking.



663
664
665
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 663

def lock(locks = true)
  spawn.lock!(locks)
end

#lock!(locks = true) ⇒ Object

:nodoc:



667
668
669
670
671
672
673
674
675
676
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 667

def lock!(locks = true) # :nodoc:
  case locks
  when String, TrueClass, NilClass
    self.lock_value = locks || true
  else
    self.lock_value = false
  end

  self
end

#noneObject

Returns a chainable relation with zero records.

The returned relation implements the Null Object pattern. It is an object with defined null behavior and always returns an empty array of records without querying the database.

Any subsequent condition chained to the returned relation will continue generating an empty relation and will not fire any query to the database.

Used in cases where a method or scope could return zero records but the result needs to be chainable.

For example:

@posts = current_user.visible_posts.where(name: params[:name])
# => the visible_posts method is expected to return a chainable Relation

def visible_posts
  case role
  when 'Country Manager'
    Post.where(country: country)
  when 'Reviewer'
    Post.published
  when 'Bad User'
    Post.none # It can't be chained if [] is returned.
  end
end


706
707
708
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 706

def none
  where("1=0").extending!(NullRelation)
end

#none!Object

:nodoc:



710
711
712
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 710

def none! # :nodoc:
  where!("1=0").extending!(NullRelation)
end

#offset(value) ⇒ Object

Specifies the number of rows to skip before returning rows.

User.offset(10) # generated SQL has "OFFSET 10"

Should be used with order.

User.offset(10).order("name ASC")


652
653
654
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 652

def offset(value)
  spawn.offset!(value)
end

#offset!(value) ⇒ Object

:nodoc:



656
657
658
659
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 656

def offset!(value) # :nodoc:
  self.offset_value = value
  self
end

#or(other) ⇒ Object

Returns a new relation, which is the logical union of this relation and the one passed as an argument.

The two relations must be structurally compatible: they must be scoping the same model, and they must differ only by where (if no group has been defined) or having (if a group is present). Neither relation may have a limit, offset, or uniq set.

Post.where("id = 1").or(Post.where("id = 2"))
# SELECT `posts`.* FROM `posts`  WHERE (('id = 1' OR 'id = 2'))


595
596
597
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 595

def or(other)
  spawn.or!(other)
end

#or!(other) ⇒ Object

:nodoc:



599
600
601
602
603
604
605
606
607
608
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 599

def or!(other) # :nodoc:
  unless structurally_compatible_for_or?(other)
    raise ArgumentError, 'Relation passed to #or must be structurally compatible'
  end

  self.where_clause = self.where_clause.or(other.where_clause)
  self.having_clause = self.having_clause.or(other.having_clause)

  self
end

#order(*args) ⇒ Object

Allows to specify an order attribute:

User.order(:name)
=> SELECT "users".* FROM "users" ORDER BY "users"."name" ASC

User.order(email: :desc)
=> SELECT "users".* FROM "users" ORDER BY "users"."email" DESC

User.order(:name, email: :desc)
=> SELECT "users".* FROM "users" ORDER BY "users"."name" ASC, "users"."email" DESC

User.order('name')
=> SELECT "users".* FROM "users" ORDER BY name

User.order('name DESC')
=> SELECT "users".* FROM "users" ORDER BY name DESC

User.order('name DESC, email')
=> SELECT "users".* FROM "users" ORDER BY name DESC, email


312
313
314
315
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 312

def order(*args)
  check_if_method_has_arguments!(:order, args)
  spawn.order!(*args)
end

#order!(*args) ⇒ Object

:nodoc:



317
318
319
320
321
322
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 317

def order!(*args) # :nodoc:
  preprocess_order_args(args)

  self.order_values += args
  self
end

#preload(*args) ⇒ Object

Allows preloading of args, in the same way that includes does:

User.preload(:posts)
=> SELECT "posts".* FROM "posts" WHERE "posts"."user_id" IN (1, 2, 3)


172
173
174
175
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 172

def preload(*args)
  check_if_method_has_arguments!(:preload, args)
  spawn.preload!(*args)
end

#preload!(*args) ⇒ Object

:nodoc:



177
178
179
180
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 177

def preload!(*args) # :nodoc:
  self.preload_values += args
  self
end

#readonly(value = true) ⇒ Object

Sets readonly attributes for the returned relation. If value is true (default), attempting to update a record will result in an error.

users = User.readonly
users.first.save
=> ActiveRecord::ReadOnlyRecord: ActiveRecord::ReadOnlyRecord


720
721
722
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 720

def readonly(value = true)
  spawn.readonly!(value)
end

#readonly!(value = true) ⇒ Object

:nodoc:



724
725
726
727
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 724

def readonly!(value = true) # :nodoc:
  self.readonly_value = value
  self
end

#references(*table_names) ⇒ Object

Use to indicate that the given table_names are referenced by an SQL string, and should therefore be JOINed in any query rather than loaded separately. This method only works in conjunction with includes. See #includes for more details.

User.includes(:posts).where("posts.name = 'foo'")
# => Doesn't JOIN the posts table, resulting in an error.

User.includes(:posts).where("posts.name = 'foo'").references(:posts)
# => Query now knows the string references posts, so adds a JOIN


192
193
194
195
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 192

def references(*table_names)
  check_if_method_has_arguments!(:references, table_names)
  spawn.references!(*table_names)
end

#references!(*table_names) ⇒ Object

:nodoc:



197
198
199
200
201
202
203
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 197

def references!(*table_names) # :nodoc:
  table_names.flatten!
  table_names.map!(&:to_s)

  self.references_values |= table_names
  self
end

#reorder(*args) ⇒ Object

Replaces any existing order defined on the relation with the specified order.

User.order('email DESC').reorder('id ASC') # generated SQL has 'ORDER BY id ASC'

Subsequent calls to order on the same relation will be appended. For example:

User.order('email DESC').reorder('id ASC').order('name ASC')

generates a query with 'ORDER BY id ASC, name ASC'.



333
334
335
336
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 333

def reorder(*args)
  check_if_method_has_arguments!(:reorder, args)
  spawn.reorder!(*args)
end

#reorder!(*args) ⇒ Object

:nodoc:



338
339
340
341
342
343
344
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 338

def reorder!(*args) # :nodoc:
  preprocess_order_args(args)

  self.reordering_value = true
  self.order_values = args
  self
end

#reverse_orderObject

Reverse the existing order clause on the relation.

User.order('name ASC').reverse_order # generated SQL has 'ORDER BY name DESC'


858
859
860
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 858

def reverse_order
  spawn.reverse_order!
end

#reverse_order!Object

:nodoc:



862
863
864
865
866
867
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 862

def reverse_order! # :nodoc:
  orders = order_values.uniq
  orders.reject!(&:blank?)
  self.order_values = reverse_sql_order(orders)
  self
end

#rewhere(conditions) ⇒ Object

Allows you to change a previously set where condition for a given attribute, instead of appending to that condition.

Post.where(trashed: true).where(trashed: false)                       # => WHERE `trashed` = 1 AND `trashed` = 0
Post.where(trashed: true).rewhere(trashed: false)                     # => WHERE `trashed` = 0
Post.where(active: true).where(trashed: true).rewhere(trashed: false) # => WHERE `active` = 1 AND `trashed` = 0

This is short-hand for unscope(where: conditions.keys).where(conditions). Note that unlike reorder, we're only unscoping the named conditions – not the entire where statement.



581
582
583
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 581

def rewhere(conditions)
  unscope(where: conditions.keys).where(conditions)
end

#select(*fields) ⇒ Object

Works in two unique ways.

First: takes a block so it can be used just like Array#select.

Model.all.select { |m| m.field == value }

This will build an array of objects from the database for the scope, converting them into an array and iterating through them using Array#select.

Second: Modifies the SELECT statement for the query so that only certain fields are retrieved:

Model.select(:field)
# => [#<Model id: nil, field: "value">]

Although in the above example it looks as though this method returns an array, it actually returns a relation object and can have other query methods appended to it, such as the other methods in ActiveRecord::QueryMethods.

The argument to the method can also be an array of fields.

Model.select(:field, :other_field, :and_one_more)
# => [#<Model id: nil, field: "value", other_field: "value", and_one_more: "value">]

You can also use one or more strings, which will be used unchanged as SELECT fields.

Model.select('field AS field_one', 'other_field AS field_two')
# => [#<Model id: nil, field: "value", other_field: "value">]

If an alias was specified, it will be accessible from the resulting objects:

Model.select('field AS field_one').first.field_one
# => "value"

Accessing attributes of an object that do not have fields retrieved by a select except id will throw ActiveModel::MissingAttributeError:

Model.select(:field).first.other_field
# => ActiveModel::MissingAttributeError: missing attribute: other_field


244
245
246
247
248
249
250
251
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 244

def select(*fields)
  if block_given?
    to_a.select { |*block_args| yield(*block_args) }
  else
    raise ArgumentError, 'Call this with at least one field' if fields.empty?
    spawn._select!(*fields)
  end
end

#unscope(*args) ⇒ Object

Removes an unwanted relation that is already defined on a chain of relations. This is useful when passing around chains of relations and would like to modify the relations without reconstructing the entire chain.

User.order('email DESC').unscope(:order) == User.all

The method arguments are symbols which correspond to the names of the methods which should be unscoped. The valid arguments are given in VALID_UNSCOPING_VALUES. The method can also be called with multiple arguments. For example:

User.order('email DESC').select('id').where(name: "John")
    .unscope(:order, :select, :where) == User.all

One can additionally pass a hash as an argument to unscope specific :where values. This is done by passing a hash with a single key-value pair. The key should be :where and the value should be the where value to unscope. For example:

User.where(name: "John", active: true).unscope(where: :name)
    == User.where(active: true)

This method is similar to except, but unlike except, it persists across merges:

User.order('email').merge(User.except(:order))
    == User.order('email')

User.order('email').merge(User.unscope(:order))
    == User.all

This means it can be used in association definitions:

has_many :comments, -> { unscope where: :trashed }


383
384
385
386
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 383

def unscope(*args)
  check_if_method_has_arguments!(:unscope, args)
  spawn.unscope!(*args)
end

#unscope!(*args) ⇒ Object

:nodoc:



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 388

def unscope!(*args) # :nodoc:
  args.flatten!
  self.unscope_values += args

  args.each do |scope|
    case scope
    when Symbol
      symbol_unscoping(scope)
    when Hash
      scope.each do |key, target_value|
        if key != :where
          raise ArgumentError, "Hash arguments in .unscope(*args) must have :where as the key."
        end

        target_values = Array(target_value).map(&:to_s)
        self.where_clause = where_clause.except(*target_values)
      end
    else
      raise ArgumentError, "Unrecognized scoping: #{args.inspect}. Use .unscope(where: :attribute_name) or .unscope(:order), for example."
    end
  end

  self
end

#where!(opts, *rest) ⇒ Object

:nodoc:



563
564
565
566
567
568
569
570
571
# File 'activerecord/lib/active_record/relation/query_methods.rb', line 563

def where!(opts, *rest) # :nodoc:
  if Hash === opts
    opts = sanitize_forbidden_attributes(opts)
    references!(PredicateBuilder.references(opts))
  end

  self.where_clause += where_clause_factory.build(opts, rest)
  self
end