From 1cd8e71d2187a1e8f7497a39e7b191b576fefbb0 Mon Sep 17 00:00:00 2001 From: Andrey Nering Date: Mon, 15 Dec 2014 13:28:01 -0200 Subject: Adding method chaining section on ActiveRecord querying guide [ci skip] --- guides/source/active_record_querying.md | 35 +++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'guides/source') diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index e1a465c64f..a32265e0db 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -9,6 +9,7 @@ After reading this guide, you will know: * How to specify the order, retrieved attributes, grouping, and other properties of the found records. * How to use eager loading to reduce the number of database queries needed for data retrieval. * How to use dynamic finders methods. +* How to use method chaining to use multiple ActiveRecord methods together. * How to check for the existence of particular records. * How to perform various calculations on Active Record models. * How to run EXPLAIN on relations. @@ -1327,6 +1328,40 @@ You can specify an exclamation point (`!`) on the end of the dynamic finders to If you want to find both by name and locked, you can chain these finders together by simply typing "`and`" between the fields. For example, `Client.find_by_first_name_and_locked("Ryan", true)`. +Understanding The Method Chaining +--------------------------------- + +The ActiveRecord pattern implements [Method Chaining](http://en.wikipedia.org/wiki/Method_chaining). +This allow us to use multiple ActiveRecord methods in a simple and straightforward way. + +You can chain a method in a sentence when the previous method called returns `ActiveRecord::Relation`, +like `all`, `where`, and `joins`. Methods that returns a instance of a single object +(see [Retrieving a Single Object Section](#retrieving-a-single-object)) have to be be the last +in the sentence. + +This guide won't cover all the possibilities, just a few as example. + +### Retrieving filtered data from multiple tables + +```ruby +Person + .select('people.id, people.name, comments.text') + .joins(:comments) + .where('comments.create_at > ?', 1.week.ago) +``` + +### Retrieving specific data from multiple tables + +```ruby +Person + .select('people.id, people.name, companies.name') + .joins(:company) + .find_by('people.name' => 'John') # this should be the last +``` + +NOTE: Remember that, if `find_by` return more than one registry, it will take just the first +and ignore the others. + Find or Build a New Object -------------------------- -- cgit v1.2.3