Class: ActiveRecord::Relation
- Inherits:
-
Object
- Object
- ActiveRecord::Relation
- Includes:
- Batches, Calculations, 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, :reorder, :reverse_order]
Constants included from SpawnMethods
SpawnMethods::VALID_FIND_OPTIONS
Instance Attribute Summary collapse
-
#default_scoped ⇒ Object
(also: #default_scoped?)
Returns the value of attribute default_scoped.
-
#extensions ⇒ Object
Returns the value of attribute extensions.
-
#klass ⇒ Object
readonly
Returns the value of attribute klass.
-
#loaded ⇒ Object
(also: #loaded?)
readonly
Returns the value of attribute loaded.
-
#table ⇒ Object
readonly
Returns the value of attribute table.
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, #reorder_value, #reverse_order_value, #select_values, #where_values
Instance Method Summary collapse
- #==(other) ⇒ Object
- #any? ⇒ Boolean
-
#as_json(options = nil) ⇒ Object
:nodoc:.
- #create(*args, &block) ⇒ Object
- #create!(*args, &block) ⇒ Object
-
#delete(id_or_array) ⇒ Object
Deletes the row with a primary key matching the
id
argument, using a SQLDELETE
statement, and returns the number of rows deleted. -
#delete_all(conditions = nil) ⇒ Object
Deletes the records matching
conditions
without instantiating the records first, and hence not calling thedestroy
method nor invoking callbacks. -
#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.
-
#destroy_all(conditions = nil) ⇒ Object
Destroys the records matching
conditions
by instantiating each record and calling itsdestroy
method. - #eager_loading? ⇒ Boolean
-
#empty? ⇒ Boolean
Returns true if there are no records.
-
#initialize(klass, table) ⇒ Relation
constructor
A new instance of Relation.
- #initialize_copy(other) ⇒ Object
- #insert(values) ⇒ Object
- #inspect ⇒ Object
-
#joined_includes_values ⇒ Object
Joins that are also marked for preloading.
- #many? ⇒ Boolean
- #new(*args, &block) ⇒ Object (also: #build)
- #reload ⇒ Object
- #reset ⇒ Object
- #respond_to?(method, include_private = false) ⇒ Boolean
- #scope_for_create ⇒ Object
-
#scoping ⇒ Object
Scope all queries to the current scope.
-
#size ⇒ Object
Returns size of the records.
- #to_a ⇒ Object
- #to_sql ⇒ Object
-
#update(id, attributes) ⇒ Object
Updates an object (or multiple objects) and saves it to the database, if validations pass.
-
#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.
- #where_values_hash ⇒ Object
-
#with_default_scope ⇒ Object
:nodoc:.
Methods included from FinderMethods
#all, #exists?, #find, #first, #first!, #last, #last!
Methods included from Calculations
#average, #calculate, #count, #maximum, #minimum, #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, #where
Methods included from Batches
Constructor Details
#initialize(klass, table) ⇒ Relation
Returns a new instance of Relation.
23 24 25 26 27 28 29 30 31 32 33 34 |
# File 'lib/active_record/relation.rb', line 23 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
#method_missing(method, *args, &block) ⇒ Object (protected)
452 453 454 455 456 457 458 459 460 461 462 |
# File 'lib/active_record/relation.rb', line 452 def method_missing(method, *args, &block) if Array.method_defined?(method) to_a.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) else super end end |
Instance Attribute Details
#default_scoped ⇒ Object Also known as: default_scoped?
Returns the value of attribute default_scoped.
19 20 21 |
# File 'lib/active_record/relation.rb', line 19 def default_scoped @default_scoped end |
#extensions ⇒ Object
Returns the value of attribute extensions.
19 20 21 |
# File 'lib/active_record/relation.rb', line 19 def extensions @extensions end |
#klass ⇒ Object (readonly)
Returns the value of attribute klass.
18 19 20 |
# File 'lib/active_record/relation.rb', line 18 def klass @klass end |
#loaded ⇒ Object (readonly) Also known as: loaded?
Returns the value of attribute loaded.
18 19 20 |
# File 'lib/active_record/relation.rb', line 18 def loaded @loaded end |
#table ⇒ Object (readonly)
Returns the value of attribute table.
18 19 20 |
# File 'lib/active_record/relation.rb', line 18 def table @table end |
Instance Method Details
#==(other) ⇒ Object
427 428 429 430 431 432 433 434 |
# File 'lib/active_record/relation.rb', line 427 def ==(other) case other when Relation other.to_sql == to_sql when Array to_a == other end end |
#any? ⇒ Boolean
154 155 156 157 158 159 160 |
# File 'lib/active_record/relation.rb', line 154 def any? if block_given? to_a.any? { |*block_args| yield(*block_args) } else !empty? end end |
#as_json(options = nil) ⇒ Object
:nodoc:
137 138 139 |
# File 'lib/active_record/relation.rb', line 137 def as_json( = nil) #:nodoc: to_a.as_json() 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 |
#create!(*args, &block) ⇒ Object
94 95 96 |
# File 'lib/active_record/relation.rb', line 94 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 id
s.
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])
379 380 381 382 |
# File 'lib/active_record/relation.rb', line 379 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 withfind
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.
346 347 348 349 350 351 352 353 354 355 356 357 |
# File 'lib/active_record/relation.rb', line 346 def delete_all(conditions = nil) 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)
319 320 321 322 323 324 325 |
# File 'lib/active_record/relation.rb', line 319 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
292 293 294 295 296 297 298 |
# File 'lib/active_record/relation.rb', line 292 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
413 414 415 416 417 |
# File 'lib/active_record/relation.rb', line 413 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.
147 148 149 150 151 152 |
# File 'lib/active_record/relation.rb', line 147 def empty? return @records.empty? if loaded? c = count c.respond_to?(:zero?) ? c.zero? : c.empty? end |
#initialize_copy(other) ⇒ Object
83 84 85 86 |
# File 'lib/active_record/relation.rb', line 83 def initialize_copy(other) @bind_values = @bind_values.dup reset end |
#insert(values) ⇒ Object
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 74 75 76 77 |
# File 'lib/active_record/relation.rb', line 36 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
436 437 438 |
# File 'lib/active_record/relation.rb', line 436 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] }
423 424 425 |
# File 'lib/active_record/relation.rb', line 423 def joined_includes_values @includes_values & @joins_values end |
#many? ⇒ Boolean
162 163 164 165 166 167 168 |
# File 'lib/active_record/relation.rb', line 162 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
79 80 81 |
# File 'lib/active_record/relation.rb', line 79 def new(*args, &block) scoping { @klass.new(*args, &block) } end |
#reload ⇒ Object
384 385 386 387 388 |
# File 'lib/active_record/relation.rb', line 384 def reload reset to_a # force reload self end |
#reset ⇒ Object
390 391 392 393 394 395 |
# File 'lib/active_record/relation.rb', line 390 def reset @first = @last = @to_sql = @order_clause = @scope_for_create = @arel = @loaded = nil @should_eager_load = @join_dependency = nil @records = [] self end |
#respond_to?(method, include_private = false) ⇒ Boolean
98 99 100 101 102 103 |
# File 'lib/active_record/relation.rb', line 98 def respond_to?(method, include_private = false) arel.respond_to?(method, include_private) || Array.method_defined?(method) || @klass.respond_to?(method, include_private) || super end |
#scope_for_create ⇒ Object
409 410 411 |
# File 'lib/active_record/relation.rb', line 409 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.
180 181 182 |
# File 'lib/active_record/relation.rb', line 180 def scoping @klass.send(:with_scope, self, :overwrite) { yield } end |
#size ⇒ Object
Returns size of the records.
142 143 144 |
# File 'lib/active_record/relation.rb', line 142 def size loaded? ? @records.length : count end |
#to_a ⇒ Object
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 |
# File 'lib/active_record/relation.rb', line 105 def to_a return @records if loaded? default_scoped = with_default_scope if default_scoped.equal?(self) @records = if @readonly_value.nil? && !@klass.locking_enabled? eager_loading? ? find_with_associations : @klass.find_by_sql(arel, @bind_values) else IdentityMap.without do eager_loading? ? find_with_associations : @klass.find_by_sql(arel, @bind_values) end end preload = @preload_values preload += @includes_values unless eager_loading? preload.each do |associations| ActiveRecord::Associations::Preloader.new(@records, associations).run end # @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 else @records = default_scoped.to_a end @loaded = true @records end |
#to_sql ⇒ Object
397 398 399 |
# File 'lib/active_record/relation.rb', line 397 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)
254 255 256 257 258 259 260 261 262 263 |
# File 'lib/active_record/relation.rb', line 254 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 |
#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')
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 |
# File 'lib/active_record/relation.rb', line 215 def update_all(updates, conditions = nil, = {}) IdentityMap.repository[symbolized_base_class].clear if IdentityMap.enabled? if conditions || .present? where(conditions).(.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
401 402 403 404 405 406 407 |
# File 'lib/active_record/relation.rb', line 401 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:
440 441 442 443 444 445 446 447 448 |
# File 'lib/active_record/relation.rb', line 440 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 |