References function in rails 4 - ruby-on-rails-4

Question

I'm just not understand the new references() function in Rails 4
I'm reading the definition here : http://apidock.com/rails/ActiveRecord/QueryMethods/references
It's meaby a english problem, but it's still not clear for me.
What is the goal of this new feature? (code was working well without it before).
Must I always add a reference for each table of my includes() ?
Thanks

Answer 1

When using includes, Rails will usually load the results separately. For example, if you do
Post.includes(:comments)
it will issue a query to load the post(s) and then another to load the comments with the post_id of the post(s).
It will generate a join, if, for example, you want to do
Post.includes(:comments).where(comments: { user_id: 44})
Where one of the conditions is dependent on a related table. If, however, you were to use
Post.includes(:comments).where('comments.user_id = ?', 44)
You will get an error in Rails 4. Any time that you're referencing a relationship in a conditional using a SQL snippet, you will have to use references. To fix the above, we would do
Post.includes(:comments).where('comments.user_id = ?', 44).references(:comments)
The other option, of course, is to not use SQL snippets in your conditionals, like the second code example, but it's not always possible to avoid them.

Answer 2

I think this is intended for when you're eager loading an association and you're using a string condition. Because Rails doesn't want to have to parse raw SQL in where clauses to figure out what you're doing, so references is intended to make it more explicit what is going on in your query.
Group.includes(:users).where('users.first_name = ?', 'John')
You should get some kind of deprecation warning if you do this. But if you use a hash syntax you should not get the deprecation warning:
Group.includes(:users).where(users: { first_name: 'John' })
So to fix the deprecation warning on the first one, you would add references(:users) to it.
Group.includes(:users).where('users.first_name = ?', 'John').references(:users)

Answer 3

The query method references is used to indicate that an association is referenced by a SQL string and therefore be joined over being loaded separately. As of Rails 4.1, adding a string condition of an included reference will result in an exception being raised.
Here is an example that selects all Teams which have a member named Nishant:
>> Team.includes(:members).where('members.name = ?', 'Nishant')
SQLite3::SQLException: no such column: members.name: SELECT "teams".*
FROM "teams" WHERE (members.name = 'Nishant')
ActiveRecord::StatementInvalid: SQLite3::SQLException: no such column:
members.name: SELECT "teams".* FROM "teams" WHERE (members.name =
'Nishant')
...
To get the above example to work in Rails 4.1, we must include query method references with the name of the association to join
Team.includes(:members).where("members.name = ?", 'Nishant').references(:members)
However, if you were using the hash syntax with association conditions, it would still perform a LEFT OUTER JOIN without any exception being raised:
Team.includes(:members).where(members: { name: 'Nishant' })
Note that ordering string SQL snippets on included associations will still work the same way without the need
of references:
Team.includes(:members).order('members.name')
I hope this will help you.