From edf32cea3f7cfb1e485c1862e3db9d216484e23b Mon Sep 17 00:00:00 2001 From: Marcel Molina Date: Wed, 5 Dec 2007 17:37:18 +0000 Subject: 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 --- activerecord/CHANGELOG | 2 ++ activerecord/lib/active_record/base.rb | 26 +++++++++++++++++++++++--- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG index 920b70046b..5c5b15e33a 100644 --- a/activerecord/CHANGELOG +++ b/activerecord/CHANGELOG @@ -1,5 +1,7 @@ *SVN* +* More complete documentation for find_by_sql. Closes #7912 [fearoffish] + * Document API for exists?'s parameter and provide examples of usage. Closes #7913 [fearoffish] * Document API for create's attributes parameter and provide examples. Closes #7915 [fearoffish] diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index 4b1693272f..506ea5621e 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -454,9 +454,29 @@ module ActiveRecord #:nodoc: end end - # Works like find(:all), but requires a complete SQL string. Examples: - # Post.find_by_sql "SELECT p.*, c.author FROM posts p, comments c WHERE p.id = c.post_id" - # Post.find_by_sql ["SELECT * FROM posts WHERE author = ? AND created > ?", author_id, start_date] + # + # Executes a custom sql query against your database and returns all the results. The results will + # be returned as an array with columns requested encapsulated as attributes of the model you call + # this method from. If you call +Product.find_by_sql+ then the results will be returned in a Product + # object with the attributes you specified in the SQL query. + # + # If you call a complicated SQL query which spans multiple tables the columns specified by the + # SELECT will be attributes of the model, whether or not they are columns of the corresponding + # table. + # + # The +sql+ parameter is a full sql query as a string. It will be called as is, there will be + # no database agnostic conversions performed. This should be a last resort because using, for example, + # MySQL specific terms will lock you to using that particular database engine or require you to + # change your call if you switch engines + # + # ==== Examples + # # A simple sql query spanning multiple tables + # Post.find_by_sql "SELECT p.title, c.author FROM posts p, comments c WHERE p.id = c.post_id" + # > [#"Ruby Meetup", "first_name"=>"Quentin"}>, ...] + # + # # You can use the same string replacement techniques as you can with ActiveRecord#find + # Post.find_by_sql ["SELECT title FROM posts WHERE author = ? AND created > ?", author_id, start_date] + # > [#"The Cheap Man Buys Twice"}>, ...] def find_by_sql(sql) connection.select_all(sanitize_sql(sql), "#{name} Load").collect! { |record| instantiate(record) } end -- cgit v1.2.3