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]
- SINGLE_VALUE_METHODS =
[:limit, :offset, :lock, :readonly, :create_with, :from]
Constants included from SpawnMethods
SpawnMethods::VALID_FIND_OPTIONS
Instance Attribute Summary collapse
-
#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
#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_flag, #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
- #inspect ⇒ Object
- #many? ⇒ Boolean
- #new(*args, &block) ⇒ Object (also: #build)
- #primary_key ⇒ Object
- #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
Methods included from FinderMethods
#all, #exists?, #find, #first, #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, #build_arel, #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 Batches
Constructor Details
#initialize(klass, table) ⇒ Relation
Returns a new instance of Relation.
20 21 22 23 24 25 26 27 28 29 |
# File '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
#method_missing(method, *args, &block) ⇒ Object (protected)
361 362 363 364 365 366 367 368 369 370 371 372 373 |
# File 'lib/active_record/relation.rb', line 361 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) else super end end |
Instance Attribute Details
#extensions ⇒ Object
Returns the value of attribute extensions.
17 18 19 |
# File 'lib/active_record/relation.rb', line 17 def extensions @extensions end |
#klass ⇒ Object (readonly)
Returns the value of attribute klass.
16 17 18 |
# File 'lib/active_record/relation.rb', line 16 def klass @klass end |
#loaded ⇒ Object (readonly) Also known as: loaded?
Returns the value of attribute loaded.
16 17 18 |
# File 'lib/active_record/relation.rb', line 16 def loaded @loaded end |
#table ⇒ Object (readonly)
Returns the value of attribute table.
16 17 18 |
# File 'lib/active_record/relation.rb', line 16 def table @table end |
Instance Method Details
#==(other) ⇒ Object
346 347 348 349 350 351 352 353 |
# File 'lib/active_record/relation.rb', line 346 def ==(other) case other when Relation other.to_sql == to_sql when Array to_a == other.to_a end end |
#any? ⇒ Boolean
93 94 95 96 97 98 99 |
# File 'lib/active_record/relation.rb', line 93 def any? if block_given? to_a.any? { |*block_args| yield(*block_args) } else !empty? end end |
#as_json(options = nil) ⇒ Object
:nodoc:
79 80 81 |
# File 'lib/active_record/relation.rb', line 79 def as_json( = nil) #:nodoc: to_a.as_json() end |
#create(*args, &block) ⇒ Object
41 42 43 |
# File 'lib/active_record/relation.rb', line 41 def create(*args, &block) scoping { @klass.create(*args, &block) } end |
#create!(*args, &block) ⇒ Object
45 46 47 |
# File 'lib/active_record/relation.rb', line 45 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])
296 297 298 |
# File 'lib/active_record/relation.rb', line 296 def delete(id_or_array) where(@klass.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'])
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.
272 273 274 |
# File 'lib/active_record/relation.rb', line 272 def delete_all(conditions = nil) conditions ? where(conditions).delete_all : arel.delete.tap { reset } 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)
246 247 248 249 250 251 252 |
# File 'lib/active_record/relation.rb', line 246 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")
219 220 221 222 223 224 225 |
# File 'lib/active_record/relation.rb', line 219 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
342 343 344 |
# File 'lib/active_record/relation.rb', line 342 def eager_loading? @should_eager_load ||= (@eager_load_values.any? || (@includes_values.any? && references_eager_loaded_tables?)) end |
#empty? ⇒ Boolean
Returns true if there are no records.
89 90 91 |
# File 'lib/active_record/relation.rb', line 89 def empty? loaded? ? @records.empty? : count.zero? end |
#initialize_copy(other) ⇒ Object
35 36 37 |
# File 'lib/active_record/relation.rb', line 35 def initialize_copy(other) reset end |
#inspect ⇒ Object
355 356 357 |
# File 'lib/active_record/relation.rb', line 355 def inspect to_a.inspect end |
#many? ⇒ Boolean
101 102 103 104 105 106 107 |
# File 'lib/active_record/relation.rb', line 101 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
31 32 33 |
# File 'lib/active_record/relation.rb', line 31 def new(*args, &block) scoping { @klass.new(*args, &block) } end |
#primary_key ⇒ Object
313 314 315 |
# File 'lib/active_record/relation.rb', line 313 def primary_key @primary_key ||= table[@klass.primary_key] end |
#reload ⇒ Object
300 301 302 303 304 |
# File 'lib/active_record/relation.rb', line 300 def reload reset to_a # force reload self end |
#reset ⇒ Object
306 307 308 309 310 311 |
# File 'lib/active_record/relation.rb', line 306 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
49 50 51 52 53 54 55 56 57 58 59 |
# File '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 |
#scope_for_create ⇒ Object
332 333 334 335 336 337 338 339 340 |
# File 'lib/active_record/relation.rb', line 332 def scope_for_create @scope_for_create ||= begin if @create_with_value @create_with_value.reverse_merge(where_values_hash) else where_values_hash end end 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.
119 120 121 122 123 124 125 126 |
# File 'lib/active_record/relation.rb', line 119 def scoping @klass.scoped_methods << self begin yield ensure @klass.scoped_methods.pop end end |
#size ⇒ Object
Returns size of the records.
84 85 86 |
# File 'lib/active_record/relation.rb', line 84 def size loaded? ? @records.length : count end |
#to_a ⇒ Object
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 |
# File '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 |
#to_sql ⇒ Object
317 318 319 |
# File 'lib/active_record/relation.rb', line 317 def to_sql @to_sql ||= arel.to_sql 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)
182 183 184 185 186 187 188 189 190 191 |
# File 'lib/active_record/relation.rb', line 182 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
153 154 155 156 157 158 159 160 161 162 163 164 |
# File 'lib/active_record/relation.rb', line 153 def update_all(updates, conditions = nil, = {}) if conditions || .present? where(conditions).(.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 |
#where_values_hash ⇒ Object
321 322 323 324 325 326 327 328 329 330 |
# File 'lib/active_record/relation.rb', line 321 def where_values_hash Hash[@where_values.find_all { |w| w.respond_to?(:operator) && w.operator == :== && w.left.relation.name == table_name }.map { |where| [ where.left.name, where.right.respond_to?(:value) ? where.right.value : where.right ] }] end |