Class: ActiveRecord::Relation

Inherits:
Object
  • Object
show all
Includes:
Batches, Calculations, Delegation, Explain, FinderMethods, QueryMethods, SpawnMethods
Defined in:
lib/active_record/relation.rb

Overview

Active Record Relation

Defined Under Namespace

Classes: JoinOperation

Constant Summary collapse

ASSOCIATION_METHODS = 
[:includes, :eager_load, :preload]
MULTI_VALUE_METHODS = 
[:select, :group, :order, :joins, :where, :having, :bind]
SINGLE_VALUE_METHODS = 
[:limit, :offset, :lock, :readonly, :from, :reordering, :reverse_order, :uniq]

Constants included from SpawnMethods

SpawnMethods::VALID_FIND_OPTIONS

Instance Attribute Summary collapse

Attributes included from QueryMethods

#bind_values, #create_with_value, #eager_load_values, #from_value, #group_values, #having_values, #includes_values, #joins_values, #limit_value, #lock_value, #offset_value, #order_values, #preload_values, #readonly_value, #reordering_value, #reverse_order_value, #select_values, #uniq_value, #where_values

Instance Method Summary collapse

Methods included from FinderMethods

#all, #exists?, #find, #first, #first!, #last, #last!

Methods included from Calculations

#average, #calculate, #count, #maximum, #minimum, #pluck, #sum

Methods included from SpawnMethods

#apply_finder_options, #except, #merge, #only

Methods included from QueryMethods

#arel, #bind, #build_arel, #create_with, #eager_load, #extending, #from, #group, #having, #includes, #joins, #limit, #lock, #offset, #order, #preload, #readonly, #reorder, #reverse_order, #select, #uniq, #where

Methods included from Batches

#find_each, #find_in_batches

Methods included from Explain

#collecting_queries_for_explain, #exec_explain, extended, #logging_query_plan, #silence_auto_explain

Methods included from Delegation

delegate_to_scoped_klass, #respond_to?

Constructor Details

#initialize(klass, table) ⇒ Relation

Returns a new instance of Relation.



19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/active_record/relation.rb', line 19

def initialize(klass, table)
  @klass, @table = klass, table

  @implicit_readonly = nil
  @loaded            = false
  @default_scoped    = false

  SINGLE_VALUE_METHODS.each {|v| instance_variable_set(:"@#{v}_value", nil)}
  (ASSOCIATION_METHODS + MULTI_VALUE_METHODS).each {|v| instance_variable_set(:"@#{v}_values", [])}
  @extensions = []
  @create_with_value = {}
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class ActiveRecord::Delegation

Instance Attribute Details

#default_scoped ⇒ Object Also known as: default_scoped?

Returns the value of attribute default_scoped.



15
16
17
 
# File 'lib/active_record/relation.rb', line 15

def default_scoped
  @default_scoped
end

#extensions ⇒ Object

Returns the value of attribute extensions.



15
16
17
 
# File 'lib/active_record/relation.rb', line 15

def extensions
  @extensions
end

#klass ⇒ Object (readonly)

Returns the value of attribute klass.



14
15
16
 
# File 'lib/active_record/relation.rb', line 14

def klass
  @klass
end

#loaded ⇒ Object (readonly) Also known as: loaded?

Returns the value of attribute loaded.



14
15
16
 
# File 'lib/active_record/relation.rb', line 14

def loaded
  @loaded
end

#table ⇒ Object (readonly)

Returns the value of attribute table.



14
15
16
 
# File 'lib/active_record/relation.rb', line 14

def table
  @table
end

Instance Method Details

#==(other) ⇒ Object 



488
489
490
491
492
493
494
495
 
# File 'lib/active_record/relation.rb', line 488

def ==(other)
  case other
  when Relation
    other.to_sql == to_sql
  when Array
    to_a == other
  end
end

#any? ⇒ Boolean

Returns:

  • (Boolean) 


214
215
216
217
218
219
220
 
# File 'lib/active_record/relation.rb', line 214

def any?
  if block_given?
    to_a.any? { |*block_args| yield(*block_args) }
  else
    !empty?
  end
end

#as_json(options = nil) ⇒ Object

:nodoc:



197
198
199
 
# File 'lib/active_record/relation.rb', line 197

def as_json(options = nil) #:nodoc:
  to_a.as_json(options)
end

#create(*args, &block) ⇒ Object 



86
87
88
 
# File 'lib/active_record/relation.rb', line 86

def create(*args, &block)
  scoping { @klass.create(*args, &block) }
end

#create!(*args, &block) ⇒ Object 



90
91
92
 
# File 'lib/active_record/relation.rb', line 90

def create!(*args, &block)
  scoping { @klass.create!(*args, &block) }
end

#delete(id_or_array) ⇒ Object

Deletes the row with a primary key matching the id argument, using a SQL DELETE statement, and returns the number of rows deleted. Active Record objects are not instantiated, so the object’s callbacks are not executed, including any :dependent association options or Observer methods.

You can delete multiple rows at once by passing an Array of ids.

Note: Although it is often much faster than the alternative, #destroy, skipping callbacks might bypass business logic in your application that ensures referential integrity or performs other essential jobs.

Examples

# Delete a single row
Todo.delete(1)

# Delete multiple rows
Todo.delete([2,3,4])



440
441
442
443
 
# File 'lib/active_record/relation.rb', line 440

def delete(id_or_array)
  IdentityMap.remove_by_id(self.symbolized_base_class, id_or_array) if IdentityMap.enabled?
  where(primary_key => id_or_array).delete_all
end

#delete_all(conditions = nil) ⇒ Object

Deletes the records matching conditions without instantiating the records first, and hence not calling the destroy method nor invoking callbacks. This is a single SQL DELETE statement that goes straight to the database, much more efficient than destroy_all. Be careful with relations though, in particular :dependent rules defined on associations are not honored. Returns the number of rows affected.

Parameters

  • conditions - Conditions are specified the same way as with find method.

Example

Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')")
Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else'])
Post.where(:person_id => 5).where(:category => ['Something', 'Else']).delete_all

Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent associations or call your before_* or after_destroy callbacks, use the destroy_all method instead.

Raises:



405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/active_record/relation.rb', line 405

def delete_all(conditions = nil)
  raise ActiveRecordError.new("delete_all doesn't support limit scope") if self.limit_value

  IdentityMap.repository[symbolized_base_class] = {} if IdentityMap.enabled?
  if conditions
    where(conditions).delete_all
  else
    statement = arel.compile_delete
    affected = @klass.connection.delete(statement, 'SQL', bind_values)

    reset
    affected
  end
end

#destroy(id) ⇒ Object

Destroy an object (or multiple objects) that has the given id, the object is instantiated first, therefore all callbacks and filters are fired off before the object is deleted. This method is less efficient than ActiveRecord#delete but allows cleanup methods and other actions to be run.

This essentially finds the object (or multiple objects) with the given id, creates a new object from the attributes, and then calls destroy on it.

Parameters

  • id - Can be either an Integer or an Array of Integers.

Examples

# Destroy a single object
Todo.destroy(1)

# Destroy multiple objects
todos = [1,2,3]
Todo.destroy(todos)



378
379
380
381
382
383
384
 
# File 'lib/active_record/relation.rb', line 378

def destroy(id)
  if id.is_a?(Array)
    id.map { |one_id| destroy(one_id) }
  else
    find(id).destroy
  end
end

#destroy_all(conditions = nil) ⇒ Object

Destroys the records matching conditions by instantiating each record and calling its destroy method. Each object’s callbacks are executed (including :dependent association options and before_destroy/after_destroy Observer methods). Returns the collection of objects that were destroyed; each will be frozen, to reflect that no changes should be made (since they can’t be persisted).

Note: Instantiation, callback execution, and deletion of each record can be time consuming when you’re removing many records at once. It generates at least one SQL DELETE query per record (or possibly more, to enforce your callbacks). If you want to delete many rows quickly, without concern for their associations or callbacks, use delete_all instead.

Parameters

  • conditions - A string, array, or hash that specifies which records to destroy. If omitted, all records are destroyed. See the Conditions section in the introduction to ActiveRecord::Base for more information.

Examples

Person.destroy_all("last_login < '2004-04-04'")
Person.destroy_all(:status => "inactive")
Person.where(:age => 0..18).destroy_all



351
352
353
354
355
356
357
 
# File 'lib/active_record/relation.rb', line 351

def destroy_all(conditions = nil)
  if conditions
    where(conditions).destroy_all
  else
    to_a.each {|object| object.destroy }.tap { reset }
  end
end

#eager_loading? ⇒ Boolean

Returns:

  • (Boolean) 


474
475
476
477
478
 
# File 'lib/active_record/relation.rb', line 474

def eager_loading?
  @should_eager_load ||=
    @eager_load_values.any? ||
    @includes_values.any? && (joined_includes_values.any? || references_eager_loaded_tables?)
end

#empty? ⇒ Boolean

Returns true if there are no records.

Returns:

  • (Boolean) 


207
208
209
210
211
212
 
# File 'lib/active_record/relation.rb', line 207

def empty?
  return @records.empty? if loaded?

  c = count
  c.respond_to?(:zero?) ? c.zero? : c.empty?
end

#explain ⇒ Object

Runs EXPLAIN on the query or queries triggered by this relation and returns the result as a string. The string is formatted imitating the ones printed by the database shell.

Note that this method actually runs the queries, since the results of some are needed by the next ones when eager loading is going on.

Please see further details in the Active Record Query Interface guide.



145
146
147
148
 
# File 'lib/active_record/relation.rb', line 145

def explain
  _, queries = collecting_queries_for_explain { exec_queries }
  exec_explain(queries)
end

#first_or_create(attributes = nil, options = {}, &block) ⇒ Object

Tries to load the first record; if it fails, then create is called with the same arguments as this method.

Expects arguments in the same format as Base.create.

Examples

# Find the first user named Penélope or create a new one.
User.where(:first_name => 'Penélope').first_or_create
# => <User id: 1, first_name: 'Penélope', last_name: nil>

# Find the first user named Penélope or create a new one.
# We already have one so the existing record will be returned.
User.where(:first_name => 'Penélope').first_or_create
# => <User id: 1, first_name: 'Penélope', last_name: nil>

# Find the first user named Scarlett or create a new one with a particular last name.
User.where(:first_name => 'Scarlett').first_or_create(:last_name => 'Johansson')
# => <User id: 2, first_name: 'Scarlett', last_name: 'Johansson'>

# Find the first user named Scarlett or create a new one with a different last name.
# We already have one so the existing record will be returned.
User.where(:first_name => 'Scarlett').first_or_create do |user|
  user.last_name = "O'Hara"
end
# => <User id: 2, first_name: 'Scarlett', last_name: 'Johansson'>



118
119
120
 
# File 'lib/active_record/relation.rb', line 118

def first_or_create(attributes = nil, options = {}, &block)
  first || create(attributes, options, &block)
end

#first_or_create!(attributes = nil, options = {}, &block) ⇒ Object

Like first_or_create but calls create! so an exception is raised if the created record is invalid.

Expects arguments in the same format as Base.create!.



125
126
127
 
# File 'lib/active_record/relation.rb', line 125

def first_or_create!(attributes = nil, options = {}, &block)
  first || create!(attributes, options, &block)
end

#first_or_initialize(attributes = nil, options = {}, &block) ⇒ Object

Like first_or_create but calls new instead of create.

Expects arguments in the same format as Base.new.



132
133
134
 
# File 'lib/active_record/relation.rb', line 132

def first_or_initialize(attributes = nil, options = {}, &block)
  first || new(attributes, options, &block)
end

#initialize_copy(other) ⇒ Object 



79
80
81
82
 
# File 'lib/active_record/relation.rb', line 79

def initialize_copy(other)
  @bind_values = @bind_values.dup
  reset
end

#insert(values) ⇒ Object 



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/active_record/relation.rb', line 32

def insert(values)
  primary_key_value = nil

  if primary_key && Hash === values
    primary_key_value = values[values.keys.find { |k|
      k.name == primary_key
    }]

    if !primary_key_value && connection.prefetch_primary_key?(klass.table_name)
      primary_key_value = connection.next_sequence_value(klass.sequence_name)
      values[klass.arel_table[klass.primary_key]] = primary_key_value
    end
  end

  im = arel.create_insert
  im.into @table

  conn = @klass.connection

  substitutes = values.sort_by { |arel_attr,_| arel_attr.name }
  binds       = substitutes.map do |arel_attr, value|
    [@klass.columns_hash[arel_attr.name], value]
  end

  substitutes.each_with_index do |tuple, i|
    tuple[1] = conn.substitute_at(binds[i][0], i)
  end

  if values.empty? # empty insert
    im.values = Arel.sql(connection.empty_insert_statement_value)
  else
    im.insert substitutes
  end

  conn.insert(
    im,
    'SQL',
    primary_key,
    primary_key_value,
    nil,
    binds)
end

#inspect ⇒ Object 



497
498
499
 
# File 'lib/active_record/relation.rb', line 497

def inspect
  to_a.inspect
end

#joined_includes_values ⇒ Object

Joins that are also marked for preloading. In which case we should just eager load them. Note that this is a naive implementation because we could have strings and symbols which represent the same association, but that aren’t matched by this. Also, we could have nested hashes which partially match, e.g. { :a => :b } & { :a => [:b, :c] }



484
485
486
 
# File 'lib/active_record/relation.rb', line 484

def joined_includes_values
  @includes_values & @joins_values
end

#many? ⇒ Boolean

Returns:

  • (Boolean) 


222
223
224
225
226
227
228
 
# File 'lib/active_record/relation.rb', line 222

def many?
  if block_given?
    to_a.many? { |*block_args| yield(*block_args) }
  else
    @limit_value ? to_a.many? : size > 1
  end
end

#new(*args, &block) ⇒ Object Also known as: build 



75
76
77
 
# File 'lib/active_record/relation.rb', line 75

def new(*args, &block)
  scoping { @klass.new(*args, &block) }
end

#reload ⇒ Object 



445
446
447
448
449
 
# File 'lib/active_record/relation.rb', line 445

def reload
  reset
  to_a # force reload
  self
end

#reset ⇒ Object 



451
452
453
454
455
456
 
# File 'lib/active_record/relation.rb', line 451

def reset
  @first = @last = @to_sql = @order_clause = @scope_for_create = @arel = @loaded = nil
  @should_eager_load = @join_dependency = nil
  @records = []
  self
end

#scope_for_create ⇒ Object 



470
471
472
 
# File 'lib/active_record/relation.rb', line 470

def scope_for_create
  @scope_for_create ||= where_values_hash.merge(create_with_value)
end

#scoping ⇒ Object

Scope all queries to the current scope.

Example

Comment.where(:post_id => 1).scoping do
  Comment.first # SELECT * FROM comments WHERE post_id = 1
end

Please check unscoped if you want to remove all previous scopes (including the default_scope) during the execution of a block.



240
241
242
 
# File 'lib/active_record/relation.rb', line 240

def scoping
  @klass.with_scope(self, :overwrite) { yield }
end

#size ⇒ Object

Returns size of the records.



202
203
204
 
# File 'lib/active_record/relation.rb', line 202

def size
  loaded? ? @records.length : count
end

#to_a ⇒ Object 



150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/active_record/relation.rb', line 150

def to_a
  # We monitor here the entire execution rather than individual SELECTs
  # because from the point of view of the user fetching the records of a
  # relation is a single unit of work. You want to know if this call takes
  # too long, not if the individual queries take too long.
  #
  # It could be the case that none of the queries involved surpass the
  # threshold, and at the same time the sum of them all does. The user
  # should get a query plan logged in that case.
  logging_query_plan do
    exec_queries
  end
end

#to_sql ⇒ Object 



458
459
460
 
# File 'lib/active_record/relation.rb', line 458

def to_sql
  @to_sql ||= klass.connection.to_sql(arel, @bind_values.dup)
end

#update(id, attributes) ⇒ Object

Updates an object (or multiple objects) and saves it to the database, if validations pass. The resulting object is returned whether the object was saved successfully to the database or not.

Parameters

  • id - This should be the id or an array of ids to be updated.

  • attributes - This should be a hash of attributes or an array of hashes.

Examples

# Updates one record
Person.update(15, :user_name => 'Samuel', :group => 'expert')

# Updates multiple records
people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } }
Person.update(people.keys, people.values)



314
315
316
317
318
319
320
321
322
 
# File 'lib/active_record/relation.rb', line 314

def update(id, attributes)
  if id.is_a?(Array)
    id.each.with_index.map {|one_id, idx| update(one_id, attributes[idx])}
  else
    object = find(id)
    object.update_attributes(attributes)
    object
  end
end

#update_all(updates, conditions = nil, options = {}) ⇒ Object

Updates all records with details given if they match a set of conditions supplied, limits and order can also be supplied. This method constructs a single SQL UPDATE statement and sends it straight to the database. It does not instantiate the involved models and it does not trigger Active Record callbacks or validations.

Parameters

  • updates - A string, array, or hash representing the SET part of an SQL statement.

  • conditions - A string, array, or hash representing the WHERE part of an SQL statement. See conditions in the intro.

  • options - Additional options are :limit and :order, see the examples for usage.

Examples

# Update all customers with the given attributes
Customer.update_all :wants_email => true

# Update all books with 'Rails' in their title
Book.update_all "author = 'David'", "title LIKE '%Rails%'"

# Update all avatars migrated more than a week ago
Avatar.update_all ['migrated_at = ?', Time.now.utc], ['migrated_at > ?', 1.week.ago]

# Update all books that match conditions, but limit it to 5 ordered by date
Book.update_all "author = 'David'", "title LIKE '%Rails%'", :order => 'created_at', :limit => 5

# Conditions from the current relation also works
Book.where('title LIKE ?', '%Rails%').update_all(:author => 'David')

# The same idea applies to limit and order
Book.where('title LIKE ?', '%Rails%').order(:created_at).limit(5).update_all(:author => 'David')



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/active_record/relation.rb', line 275

def update_all(updates, conditions = nil, options = {})
  IdentityMap.repository[symbolized_base_class].clear if IdentityMap.enabled?
  if conditions || options.present?
    where(conditions).apply_finder_options(options.slice(:limit, :order)).update_all(updates)
  else
    stmt = Arel::UpdateManager.new(arel.engine)

    stmt.set Arel.sql(@klass.send(:sanitize_sql_for_assignment, updates))
    stmt.table(table)
    stmt.key = table[primary_key]

    if joins_values.any?
      @klass.connection.join_to_update(stmt, arel)
    else
      stmt.take(arel.limit)
      stmt.order(*arel.orders)
      stmt.wheres = arel.constraints
    end

    @klass.connection.update stmt, 'SQL', bind_values
  end
end

#where_values_hash ⇒ Object 



462
463
464
465
466
467
468
 
# File 'lib/active_record/relation.rb', line 462

def where_values_hash
  equalities = with_default_scope.where_values.grep(Arel::Nodes::Equality).find_all { |node|
    node.left.relation.name == table_name
  }

  Hash[equalities.map { |where| [where.left.name, where.right] }]
end

#with_default_scope ⇒ Object

:nodoc:



501
502
503
504
505
506
507
508
509
 
# File 'lib/active_record/relation.rb', line 501

def with_default_scope #:nodoc:
  if default_scoped? && default_scope = klass.send(:build_default_scope)
    default_scope = default_scope.merge(self)
    default_scope.default_scoped = false
    default_scope
  else
    self
  end
end