1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00

Avoid orders_count in Active Record order guide examples

The ordering examples use `Customer#orders_count` for ordering which
results in beginner-unfriendly examples like:

  Customer.order(:orders_count)

Having two unrelated types of `order` can be confusing.
As Customer has many Orders it's probably better to replace the Customer
with Book to avoid any confusion.

Not having `orders_count` also makes it easier to grep for 'order' in
the guide. This also is a reason the `Order.none` example is replaced
with `Book.none`, besides it being more consistent with the example
below it.

Co-authored-by: Ryuta Kamizono <kamipo@gmail.com>
This commit is contained in:
Petrik 2021-08-16 12:25:11 +02:00
parent 6ec669b65d
commit 33114544db

View file

@ -714,40 +714,40 @@ To retrieve records from the database in a specific order, you can use the [`ord
For example, if you're getting a set of records and want to order them in ascending order by the `created_at` field in your table:
```ruby
Customer.order(:created_at)
Book.order(:created_at)
# OR
Customer.order("created_at")
Book.order("created_at")
```
You could specify `ASC` or `DESC` as well:
```ruby
Customer.order(created_at: :desc)
Book.order(created_at: :desc)
# OR
Customer.order(created_at: :asc)
Book.order(created_at: :asc)
# OR
Customer.order("created_at DESC")
Book.order("created_at DESC")
# OR
Customer.order("created_at ASC")
Book.order("created_at ASC")
```
Or ordering by multiple fields:
```ruby
Customer.order(orders_count: :asc, created_at: :desc)
Book.order(title: :asc, created_at: :desc)
# OR
Customer.order(:orders_count, created_at: :desc)
Book.order(:title, created_at: :desc)
# OR
Customer.order("orders_count ASC, created_at DESC")
Book.order("title ASC, created_at DESC")
# OR
Customer.order("orders_count ASC", "created_at DESC")
Book.order("title ASC", "created_at DESC")
```
If you want to call `order` multiple times, subsequent orders will be appended to the first:
```irb
irb> Customer.order("orders_count ASC").order("created_at DESC")
SELECT * FROM customers ORDER BY orders_count ASC, created_at DESC
irb> Book.order("title ASC").order("created_at DESC")
SELECT * FROM books ORDER BY title ASC, created_at DESC
```
WARNING: In most database systems, on selecting fields with `distinct` from a result set using methods like `select`, `pluck` and `ids`; the `order` method will raise an `ActiveRecord::StatementInvalid` exception unless the field(s) used in `order` clause are included in the select list. See the next section for selecting fields from the result set.
@ -1028,25 +1028,25 @@ SELECT * FROM books WHERE author_id = 10 ORDER BY year_published ASC
The [`reverse_order`][] method reverses the ordering clause if specified.
```ruby
Customer.where("orders_count > 10").order(:last_name).reverse_order
Book.where("author_id > 10").order(:year_published).reverse_order
```
The SQL that would be executed:
```sql
SELECT * FROM customers WHERE orders_count > 10 ORDER BY last_name DESC
SELECT * FROM books WHERE author_id > 10 ORDER BY year_published DESC
```
If no ordering clause is specified in the query, the `reverse_order` orders by the primary key in reverse order.
```ruby
Customer.where("orders_count > 10").reverse_order
Book.where("author_id > 10").reverse_order
```
The SQL that would be executed:
```sql
SELECT * FROM customers WHERE orders_count > 10 ORDER BY customers.id DESC
SELECT * FROM books WHERE author_id > 10 ORDER BY books.id DESC
```
The `reverse_order` method accepts **no** arguments.
@ -1085,7 +1085,7 @@ Null Relation
The [`none`][] method returns a chainable relation with no records. Any subsequent conditions chained to the returned relation will continue generating empty relations. This is useful in scenarios where you need a chainable response to a method or a scope that could return zero results.
```ruby
Order.none # returns an empty Relation and fires no queries.
Book.none # returns an empty Relation and fires no queries.
```
```ruby