Skip to content
This repository
Browse code

More complete documentation for find_by_sql. Closes #7912 [fearoffish]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8298 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit edf32cea3f7cfb1e485c1862e3db9d216484e23b 1 parent 971ed15
authored December 05, 2007
2  activerecord/CHANGELOG
... ...
@@ -1,5 +1,7 @@
1 1
 *SVN*
2 2
 
  3
+* More complete documentation for find_by_sql. Closes #7912 [fearoffish]
  4
+
3 5
 * Document API for exists?'s parameter and provide examples of usage. Closes #7913 [fearoffish]
4 6
 
5 7
 * Document API for create's attributes parameter and provide examples. Closes #7915 [fearoffish]
26  activerecord/lib/active_record/base.rb
@@ -454,9 +454,29 @@ def find(*args)
454 454
         end
455 455
       end
456 456
       
457  
-      # Works like find(:all), but requires a complete SQL string. Examples:
458  
-      #   Post.find_by_sql "SELECT p.*, c.author FROM posts p, comments c WHERE p.id = c.post_id"
459  
-      #   Post.find_by_sql ["SELECT * FROM posts WHERE author = ? AND created > ?", author_id, start_date]
  457
+      #
  458
+      # Executes a custom sql query against your database and returns all the results.  The results will 
  459
+      # be returned as an array with columns requested encapsulated as attributes of the model you call 
  460
+      # this method from.  If you call +Product.find_by_sql+ then the results will be returned in a Product 
  461
+      # object with the attributes you specified in the SQL query.
  462
+      #
  463
+      # If you call a complicated SQL query which spans multiple tables the columns specified by the 
  464
+      # SELECT will be attributes of the model, whether or not they are columns of the corresponding 
  465
+      # table.
  466
+      #
  467
+      # The +sql+ parameter is a full sql query as a string.  It will be called as is, there will be 
  468
+      # no database agnostic conversions performed.  This should be a last resort because using, for example,  
  469
+      # MySQL specific terms will lock you to using that particular database engine or require you to 
  470
+      # change your call if you switch engines
  471
+      #
  472
+      # ==== Examples
  473
+      #   # A simple sql query spanning multiple tables
  474
+      #   Post.find_by_sql "SELECT p.title, c.author FROM posts p, comments c WHERE p.id = c.post_id"
  475
+      #   > [#<Post:0x36bff9c @attributes={"title"=>"Ruby Meetup", "first_name"=>"Quentin"}>, ...]
  476
+      #
  477
+      #   # You can use the same string replacement techniques as you can with ActiveRecord#find
  478
+      #   Post.find_by_sql ["SELECT title FROM posts WHERE author = ? AND created > ?", author_id, start_date]
  479
+      #   > [#<Post:0x36bff9c @attributes={"first_name"=>"The Cheap Man Buys Twice"}>, ...]
460 480
       def find_by_sql(sql)
461 481
         connection.select_all(sanitize_sql(sql), "#{name} Load").collect! { |record| instantiate(record) }
462 482
       end

0 notes on commit edf32ce

Please sign in to comment.
Something went wrong with that request. Please try again.