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, #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, #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 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)
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 |
# File '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
#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
339 340 341 342 343 344 345 346 |
# File '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 |
#any? ⇒ Boolean
91 92 93 94 95 96 97 |
# File 'lib/active_record/relation.rb', line 91 def any? if block_given? to_a.any? { |*block_args| yield(*block_args) } else !empty? end end |
#as_json(options = nil) ⇒ Object
:nodoc:
79 |
# File 'lib/active_record/relation.rb', line 79 def as_json( = nil) to_a 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])
294 295 296 |
# File 'lib/active_record/relation.rb', line 294 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.
270 271 272 |
# File 'lib/active_record/relation.rb', line 270 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)
244 245 246 247 248 249 250 |
# File '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 |
#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")
217 218 219 220 221 222 223 |
# File '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 |
#eager_loading? ⇒ Boolean
335 336 337 |
# File '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 |
#empty? ⇒ Boolean
Returns true if there are no records.
87 88 89 |
# File 'lib/active_record/relation.rb', line 87 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
348 349 350 |
# File 'lib/active_record/relation.rb', line 348 def inspect to_a.inspect end |
#many? ⇒ Boolean
99 100 101 102 103 104 105 |
# File '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 |
#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
311 312 313 |
# File 'lib/active_record/relation.rb', line 311 def primary_key @primary_key ||= table[@klass.primary_key] end |
#reload ⇒ Object
298 299 300 301 302 |
# File 'lib/active_record/relation.rb', line 298 def reload reset to_a # force reload self end |
#reset ⇒ Object
304 305 306 307 308 309 |
# File '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 |
#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
329 330 331 332 333 |
# File 'lib/active_record/relation.rb', line 329 def scope_for_create @scope_for_create ||= begin @create_with_value || where_values_hash 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.
117 118 119 120 121 122 123 124 |
# File 'lib/active_record/relation.rb', line 117 def scoping @klass.scoped_methods << self begin yield ensure @klass.scoped_methods.pop end end |
#size ⇒ Object
Returns size of the records.
82 83 84 |
# File 'lib/active_record/relation.rb', line 82 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
315 316 317 |
# File 'lib/active_record/relation.rb', line 315 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)
180 181 182 183 184 185 186 187 188 189 |
# File '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 |
#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
151 152 153 154 155 156 157 158 159 160 161 162 |
# File 'lib/active_record/relation.rb', line 151 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
319 320 321 322 323 324 325 326 327 |
# File '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 |