Class: ActiveRecord::Relation

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

Overview

Active Record Relation

Defined Under Namespace

Classes: JoinOperation

Constant Summary

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

Constants included from SpawnMethods

VALID_FIND_OPTIONS

Instance Attribute Summary (collapse)

Attributes included from QueryMethods

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, select_values, where_values

Instance Method Summary (collapse)

Methods included from Batches

#find_each, #find_in_batches

Methods included from QueryMethods

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

Methods included from ActiveSupport::Concern

#append_features, extended, #included

Methods included from SpawnMethods

#apply_finder_options, #except, #merge, #only

Methods included from Calculations

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

Methods included from FinderMethods

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

Constructor Details

- (Relation) initialize(klass, table)

A new instance of Relation 



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

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

  @implicit_readonly = nil
  @loaded            = 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 = []
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(method, *args, &block) (protected) 



354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
 
# File 'activerecord/lib/active_record/relation.rb', line 354

def method_missing(method, *args, &block)
  if Array.method_defined?(method)
    to_a.send(method, *args, &block)
  elsif @klass.scopes[method]
    merge(@klass.send(method, *args, &block))
  elsif @klass.respond_to?(method)
    scoping { @klass.send(method, *args, &block) }
  elsif arel.respond_to?(method)
    arel.send(method, *args, &block)
  elsif match = DynamicFinderMatch.match(method)
    attributes = match.attribute_names
    super unless @klass.send(:all_attributes_exists?, attributes)

    if match.finder?
      find_by_attributes(match, attributes, *args)
    elsif match.instantiator?
      find_or_instantiator_by_attributes(match, attributes, *args, &block)
    end
  else
    super
  end
end

Instance Attribute Details

- (Object) extensions

Returns the value of attribute extensions 



17
18
19
 
# File 'activerecord/lib/active_record/relation.rb', line 17

def extensions
  @extensions
end

- (Object) klass (readonly)

Returns the value of attribute klass 



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

def klass
  @klass
end

- (Object) loaded (readonly) Also known as: loaded?

Returns the value of attribute loaded 



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

def loaded
  @loaded
end

- (Object) table (readonly)

Returns the value of attribute table 



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

def table
  @table
end

Instance Method Details

- (Object) ==(other) 



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

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

- (Boolean) any?

Returns:

  • (Boolean) 


91
92
93
94
95
96
97
 
# File 'activerecord/lib/active_record/relation.rb', line 91

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

- (Object) as_json(options = nil)

:nodoc: 



79
 
# File 'activerecord/lib/active_record/relation.rb', line 79

def as_json(options = nil) to_a end

- (Object) create(*args, &block) 



41
42
43
 
# File 'activerecord/lib/active_record/relation.rb', line 41

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

- (Object) create!(*args, &block) 



45
46
47
 
# File 'activerecord/lib/active_record/relation.rb', line 45

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

- (Object) delete(id_or_array)

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])


294
295
296
 
# File 'activerecord/lib/active_record/relation.rb', line 294

def delete(id_or_array)
  where(@klass.primary_key => id_or_array).delete_all
end

- (Object) delete_all(conditions = nil)

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'])

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. 



270
271
272
 
# File 'activerecord/lib/active_record/relation.rb', line 270

def delete_all(conditions = nil)
  conditions ? where(conditions).delete_all : arel.delete.tap { reset }
end

- (Object) destroy(id)

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)


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

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

- (Object) destroy_all(conditions = nil)

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")


217
218
219
220
221
222
223
 
# File 'activerecord/lib/active_record/relation.rb', line 217

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

- (Boolean) eager_loading?

Returns:

  • (Boolean) 


335
336
337
 
# File 'activerecord/lib/active_record/relation.rb', line 335

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

- (Boolean) empty?

Returns true if there are no records.

Returns:

  • (Boolean) 


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

def empty?
  loaded? ? @records.empty? : count.zero?
end

- (Object) initialize_copy(other) 



35
36
37
 
# File 'activerecord/lib/active_record/relation.rb', line 35

def initialize_copy(other)
  reset
end

- (Object) inspect 



348
349
350
 
# File 'activerecord/lib/active_record/relation.rb', line 348

def inspect
  to_a.inspect
end

- (Boolean) many?

Returns:

  • (Boolean) 


99
100
101
102
103
104
105
 
# File 'activerecord/lib/active_record/relation.rb', line 99

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

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



31
32
33
 
# File 'activerecord/lib/active_record/relation.rb', line 31

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

- (Object) primary_key 



311
312
313
 
# File 'activerecord/lib/active_record/relation.rb', line 311

def primary_key
  @primary_key ||= table[@klass.primary_key]
end

- (Object) reload 



298
299
300
301
302
 
# File 'activerecord/lib/active_record/relation.rb', line 298

def reload
  reset
  to_a # force reload
  self
end

- (Object) reset 



304
305
306
307
308
309
 
# File 'activerecord/lib/active_record/relation.rb', line 304

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

- (Boolean) respond_to?(method, include_private = false)

Returns:

  • (Boolean) 


49
50
51
52
53
54
55
56
57
58
59
 
# File 'activerecord/lib/active_record/relation.rb', line 49

def respond_to?(method, include_private = false)
  return true if arel.respond_to?(method, include_private) || Array.method_defined?(method) || @klass.respond_to?(method, include_private)

  if match = DynamicFinderMatch.match(method)
    return true if @klass.send(:all_attributes_exists?, match.attribute_names)
  elsif match = DynamicScopeMatch.match(method)
    return true if @klass.send(:all_attributes_exists?, match.attribute_names)
  else
    super
  end
end

- (Object) scope_for_create 



329
330
331
332
333
 
# File 'activerecord/lib/active_record/relation.rb', line 329

def scope_for_create
  @scope_for_create ||= begin
    @create_with_value || where_values_hash
  end
end

- (Object) scoping

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. 



117
118
119
120
121
122
123
124
 
# File 'activerecord/lib/active_record/relation.rb', line 117

def scoping
  @klass.scoped_methods << self
  begin
    yield
  ensure
    @klass.scoped_methods.pop
  end
end

- (Object) size

Returns size of the records. 



82
83
84
 
# File 'activerecord/lib/active_record/relation.rb', line 82

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

- (Object) to_a 



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'activerecord/lib/active_record/relation.rb', line 61

def to_a
  return @records if loaded?

  @records = eager_loading? ? find_with_associations : @klass.find_by_sql(arel.to_sql)

  preload = @preload_values
  preload +=  @includes_values unless eager_loading?
  preload.each {|associations| @klass.send(:preload_associations, @records, associations) }

  # @readonly_value is true only if set explicitly. @implicit_readonly is true if there
  # are JOINS and no explicit SELECT.
  readonly = @readonly_value.nil? ? @implicit_readonly : @readonly_value
  @records.each { |record| record.readonly! } if readonly

  @loaded = true
  @records
end

- (Object) to_sql 



315
316
317
 
# File 'activerecord/lib/active_record/relation.rb', line 315

def to_sql
  @to_sql ||= arel.to_sql
end

- (Object) update(id, attributes)

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)


180
181
182
183
184
185
186
187
188
189
 
# File 'activerecord/lib/active_record/relation.rb', line 180

def update(id, attributes)
  if id.is_a?(Array)
    idx = -1
    id.collect { |one_id| idx += 1; update(one_id, attributes[idx]) }
  else
    object = find(id)
    object.update_attributes(attributes)
    object
  end
end

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

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


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

def update_all(updates, conditions = nil, options = {})
  if conditions || options.present?
    where(conditions).apply_finder_options(options.slice(:limit, :order)).update_all(updates)
  else
    # Apply limit and order only if they're both present
    if @limit_value.present? == @order_values.present?
      arel.update(Arel::SqlLiteral.new(@klass.send(:sanitize_sql_for_assignment, updates)))
    else
      except(:limit, :order).update_all(updates)
    end
  end
end

- (Object) where_values_hash 



319
320
321
322
323
324
325
326
327
 
# File 'activerecord/lib/active_record/relation.rb', line 319

def where_values_hash
      Hash[@where_values.find_all { |w|
        w.respond_to?(:operator) && w.operator == :==
      }.map { |where|
        [where.operand1.name,
         where.operand2.respond_to?(:value) ?
         where.operand2.value : where.operand2]
    }]
end