aboutsummaryrefslogtreecommitdiffstats
path: root/guides/source
diff options
context:
space:
mode:
authorTim Wade <hello@timjwade.com>2015-08-22 10:53:19 -0700
committerTim Wade <hello@timjwade.com>2015-09-09 08:15:23 -0700
commita0d7db760d6d71b084981fd1fc50bf57ac25b78c (patch)
tree2ec982197a8e19cfdf56582010a724fc9497ffc7 /guides/source
parent7bd34c107aa62b469e040ed98991ea88d6667cb6 (diff)
downloadrails-a0d7db760d6d71b084981fd1fc50bf57ac25b78c.tar.gz
rails-a0d7db760d6d71b084981fd1fc50bf57ac25b78c.tar.bz2
rails-a0d7db760d6d71b084981fd1fc50bf57ac25b78c.zip
[ci skip] Improve readability in AR querying guide
* rewords a few awkwardly worded sentences * adds some punctuation * adds a few missing words
Diffstat (limited to 'guides/source')
-rw-r--r--guides/source/active_record_querying.md31
1 files changed, 15 insertions, 16 deletions
diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md
index 4b4d70d3ce..bef7524f27 100644
--- a/guides/source/active_record_querying.md
+++ b/guides/source/active_record_querying.md
@@ -10,7 +10,7 @@ After reading this guide, you will know:
* How to find records using a variety of methods and conditions.
* 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 dynamic finder 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.
@@ -390,7 +390,7 @@ Now what if that number could vary, say as an argument from somewhere? The find
Client.where("orders_count = ?", params[:orders])
```
-Active Record will go through the first element in the conditions value and any additional elements will replace the question marks `(?)` in the first element.
+Active Record will take the first argument as the conditions string and any additional arguments will replace the question marks `(?)` in it.
If you want to specify multiple conditions:
@@ -418,7 +418,7 @@ TIP: For more information on the dangers of SQL injection, see the [Ruby on Rail
#### Placeholder Conditions
-Similar to the `(?)` replacement style of params, you can also specify keys/values hash in your array conditions:
+Similar to the `(?)` replacement style of params, you can also specify keys in your conditions string along with a corresponding keys/values hash:
```ruby
Client.where("created_at >= :start_date AND created_at <= :end_date",
@@ -429,7 +429,7 @@ This makes for clearer readability if you have a large number of variable condit
### Hash Conditions
-Active Record also allows you to pass in hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want conditionalised and the values of how you want to conditionalise them:
+Active Record also allows you to pass in hash conditions which can increase the readability of your conditions syntax. With hash conditions, you pass in a hash with keys of the fields you want qualified and the values of how you want to qualify them:
NOTE: Only equality, range and subset checking are possible with Hash conditions.
@@ -529,7 +529,7 @@ Client.order("orders_count ASC, created_at DESC")
Client.order("orders_count ASC", "created_at DESC")
```
-If you want to call `order` multiple times e.g. in different context, new order will append previous one:
+If you want to call `order` multiple times, subsequent orders will be appended to the first:
```ruby
Client.order("orders_count ASC").order("created_at DESC")
@@ -617,9 +617,9 @@ SELECT * FROM clients LIMIT 5 OFFSET 30
Group
-----
-To apply a `GROUP BY` clause to the SQL fired by the finder, you can specify the `group` method on the find.
+To apply a `GROUP BY` clause to the SQL fired by the finder, you can use the `group` method.
-For example, if you want to find a collection of the dates orders were created on:
+For example, if you want to find a collection of the dates on which orders were created:
```ruby
Order.select("date(created_at) as ordered_date, sum(price) as total_price").group("date(created_at)")
@@ -637,7 +637,7 @@ GROUP BY date(created_at)
### Total of grouped items
-To get the total of grouped items on a single query call `count` after the `group`.
+To get the total of grouped items on a single query, call `count` after the `group`.
```ruby
Order.group(:status).count
@@ -673,7 +673,7 @@ GROUP BY date(created_at)
HAVING sum(price) > 100
```
-This will return single order objects for each day, but only those that are ordered more than $100 in a day.
+This returns the date and total price for each order object, grouped by the day they were ordered and where the price is more than $100.
Overriding Conditions
---------------------
@@ -703,8 +703,7 @@ Article.where(id: 10, trashed: false).unscope(where: :id)
# SELECT "articles".* FROM "articles" WHERE trashed = 0
```
-A relation which has used `unscope` will affect any relation it is
-merged in to:
+A relation which has used `unscope` will affect any relation into which it is merged:
```ruby
Article.order('id asc').merge(Article.unscope(:order))
@@ -748,7 +747,7 @@ SELECT * FROM articles WHERE id = 10
SELECT * FROM comments WHERE article_id = 10 ORDER BY name
```
-In case the `reorder` clause is not used, the SQL executed would be:
+In the case where the `reorder` clause is not used, the SQL executed would be:
```sql
SELECT * FROM articles WHERE id = 10
@@ -837,7 +836,7 @@ end
Readonly Objects
----------------
-Active Record provides `readonly` method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an `ActiveRecord::ReadOnlyRecord` exception.
+Active Record provides the `readonly` method on a relation to explicitly disallow modification of any of the returned objects. Any attempt to alter a readonly record will not succeed, raising an `ActiveRecord::ReadOnlyRecord` exception.
```ruby
client = Client.readonly.first
@@ -1050,7 +1049,7 @@ SELECT categories.* FROM categories
### Specifying Conditions on the Joined Tables
-You can specify conditions on the joined tables using the regular [Array](#array-conditions) and [String](#pure-string-conditions) conditions. [Hash conditions](#hash-conditions) provides a special syntax for specifying conditions for the joined tables:
+You can specify conditions on the joined tables using the regular [Array](#array-conditions) and [String](#pure-string-conditions) conditions. [Hash conditions](#hash-conditions) provide a special syntax for specifying conditions for the joined tables:
```ruby
time_range = (Time.now.midnight - 1.day)..Time.now.midnight
@@ -1089,7 +1088,7 @@ This code looks fine at the first sight. But the problem lies within the total n
Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the `includes` method of the `Model.find` call. With `includes`, Active Record ensures that all of the specified associations are loaded using the minimum possible number of queries.
-Revisiting the above case, we could rewrite `Client.limit(10)` to use eager load addresses:
+Revisiting the above case, we could rewrite `Client.limit(10)` to eager load addresses:
```ruby
clients = Client.includes(:address).limit(10)
@@ -1426,7 +1425,7 @@ It's common that you need to find a record or create it if it doesn't exist. You
### `find_or_create_by`
-The `find_or_create_by` method checks whether a record with the attributes exists. If it doesn't, then `create` is called. Let's see an example.
+The `find_or_create_by` method checks whether a record with the specified attributes exists. If it doesn't, then `create` is called. Let's see an example.
Suppose you want to find a client named 'Andy', and if there's none, create one. You can do so by running: