From c4193d9f8ebb22938786d0d03e82f6b7619a31dc Mon Sep 17 00:00:00 2001 From: Chris Kampmeier Date: Tue, 6 Jan 2009 22:51:57 -0800 Subject: Rewrite ActiveRecord::Base#destroy_all docs to remove incorrect info, mention return value, and improve clarity (The incorrect information is "at least 2*N database queries" -- it's N+1 at best.) --- activerecord/lib/active_record/base.rb | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 91bcb62794..43b34125be 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -851,25 +851,32 @@ module ActiveRecord #:nodoc: connection.update(sql, "#{name} Update") end - # Destroys the records matching +conditions+ by instantiating each record and calling their +destroy+ method. - # This means at least 2*N database queries to destroy N records, so avoid +destroy_all+ if you are deleting - # many records. If you want to simply delete records without worrying about dependent associations or - # callbacks, use the much faster +delete_all+ method instead. + # 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: the 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+ - Conditions are specified the same way as with +find+ method. + # * +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. # - # ==== Example + # ==== Examples # # Person.destroy_all("last_login < '2004-04-04'") - # - # This loads and destroys each person one by one, including its dependent associations and before_ and - # after_destroy callbacks. - # - # +conditions+ can be anything that +find+ also accepts: - # - # Person.destroy_all(:last_login => 6.hours.ago) + # Person.destroy_all(:status => "inactive") def destroy_all(conditions = nil) find(:all, :conditions => conditions).each { |object| object.destroy } end -- cgit v1.2.3